Register a webhook destination

Register one HTTPS destination for terminal render events. The URL must pass the same egress policy the platform applies to every outbound request: public HTTPS on port 443, no credentials, and a DNS answer set of public addresses only. Delivery rechecks all of it on every connection, so a name that later resolves privately is refused then too. The signing secret is returned in this response and never again. Every delivery carries a Thirds-Signature header of the form "t=<unix-seconds>,v1=<hex>": each v1 value is HMAC-SHA256 over the exact bytes "<t>.<body>" with one signing secret, so verify against the raw body before parsing it, and refuse a timestamp too far from your own clock to bound replays. During a rotation overlap the header carries two v1 values (the current secret's first, then the previous secret's), and a receiver accepts the delivery when any one value matches. See the webhook delivery guide for a worked receiver that verifies this header in Node or Python.

post/v1/webhooks

Request

  • Base URL: https://thirds.ai
  • URL: https://thirds.ai/v1/webhooks
  • Auth: HTTP bearer

Request body

urlstring uri required

The HTTPS URL deliveries are sent to. It must use port 443, carry no credentials, and resolve to public addresses only; private, loopback, link-local, metadata, and reserved destinations are refused, at registration and again on every delivery connection.

eventsstring[]

The terminal render events this destination receives. A body without this field selects every event.

Response

The destination was registered and is enabled. This is the only response, with rotation's, that ever carries the signing secret.

idstring required

The destination's public identifier: "wh_" followed by 32 lowercase hexadecimal characters.

urlstring uri required
eventsstring[] required

The selected events, always sorted and distinct.

status'enabled' | 'disabled' required
disabled_reason'owner_request' | 'delivery_failure' | 'null' nullable required

Why a disabled destination is disabled: the owner asked, or delivery failed repeatedly. Null while the destination is enabled.

display_prefixstring required

The first characters of the signing secret, enough to tell destinations apart in a list.

last_delivery_atstring date-time nullable required

Time of the most recent recorded attempt, including tests.

failure_countinteger required

Consecutive normal delivery failures. A success or enable resets it. Test events do not change it.

created_atstring date-time required
previous_secret_expires_atstring date-time nullable required

Set while a rotation overlap is running: until this instant every delivery also carries a signature made with the previous secret.

secretstring required

The full signing secret: "thirds_whsec_" followed by 64 lowercase hexadecimal characters. It is shown here once and never again; store it and verify every delivery's Thirds-Signature header with it.

Changes

No recorded changes to this operation across all 1 revision of this API.