Skip to main content
POST
/
orgs
/
webhooks
Register a webhook
curl --request POST \
  --url https://v2.prod.halliday.xyz/orgs/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://api.yourapp.com/halliday/webhooks",
  "label": "prod-workflows",
  "event_types": [
    "WORKFLOW_COMPLETED",
    "WORKFLOW_FAILED"
  ],
  "auth_header": {
    "name": "X-Webhook-Token",
    "value": "a-shared-secret-token"
  }
}
'
{
  "id": "4f2c…",
  "label": "prod-workflows",
  "url": "https://api.yourapp.com/halliday/webhooks",
  "signing_secret": "a1b2c3…"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
url
string<uri>
required

Receiver URL. Must be HTTPS on port 443. Private/reserved IP addresses are rejected (SSRF protection).

Example:

"https://api.yourapp.com/halliday/webhooks"

​
label
string
required

Human-readable identifier, unique per org. Used to address the webhook on update, rotate, and delete.

Example:

"prod-workflows"

​
event_types
enum<string>[]
required

At least one event type to subscribe to.

Minimum array length: 1

Event type a webhook can subscribe to. WORKFLOW_COMPLETED fires when a workflow's status becomes COMPLETE; WORKFLOW_FAILED fires when it becomes FAILED.

Available options:
WORKFLOW_COMPLETED,
WORKFLOW_FAILED
Example:
["WORKFLOW_COMPLETED", "WORKFLOW_FAILED"]
​
auth_header
object

Optional custom HTTP header that Halliday attaches to every delivery to your receiver URL, so your endpoint can authenticate inbound deliveries in addition to verifying X-Halliday-Signature. The value is write-only — it is never returned by any endpoint; the list endpoint echoes only the header name as auth_header_name.

​
signing_secret
string

Optional. Provide your own HMAC-SHA256 signing secret instead of letting Halliday generate one. Omit this to receive a generated signing_secret in the response.

Example:

"my-own-signing-secret"

Response

Webhook registered successfully

A registered webhook including its signing secret. Returned only on creation and rotation.

​
id
string
required
Example:

"4f2c…"

​
label
string
required
Example:

"prod-workflows"

​
url
string<uri>
required
Example:

"https://api.yourapp.com/halliday/webhooks"

​
signing_secret
string
required

HMAC-SHA256 signing secret. Store it now — it is never returned again from the list endpoint.

Example:

"a1b2c3…"