Skip to main content
POST
Create Webhook

Overview

Registers a webhook endpoint and returns the signing secret once in the response. Store it immediately: list and retrieve responses redact it. A newly created endpoint’s status is always active. Requires the portfolios:manage scope.

Body Parameters

string
required
HTTPS endpoint (HTTP is allowed in non-production environments only). Max 2048 chars.
string
Optional human-readable description (max 2000 chars).
string[]
required
1-20 event types: alert.created, trademark.status_changed, and office_action.issued. Any other value returns 400. The last two are accepted for subscription but are not yet emitted — they begin delivering when the API events projector is enabled. webhook.test is delivered only when you call Test Webhook; you can’t subscribe to it.
string | null
Optional ptf_* scope. Applies to every event type, alert.created included: the endpoint receives an event only when its mark was a member of this portfolio at event time. Leave it unset to receive alerts for marks you don’t own.
object
Free-form metadata.

Response

string
Endpoint ID (whk_*).
string
Always "webhook_endpoint".
string
Echo of input.
string | null
Echo of input.
string[]
Echo of input.
string | null
Portfolio scope applied to every event type, or null.
string
Always "active" on create.
integer
Starts at 1.
string
Plaintext signing secret. Returned only on this response and on rotate-secret.
integer
0 on create.
string | null
Null on create.
string | null
Null on create.
object
Echoed back.
string
ISO timestamp.
string
ISO timestamp.
string
Request identifier.

Errors

Code Examples