What webhooks do today.#
- HTTPS endpoints only. POST /api/v1/webhooks registers an endpoint with a URL, an optional description, and a list of event names. URLs that do not start with https:// are rejected.
- Signing secret shown once. The create response returns the signing secret, prefixed whsec_, exactly once. It is stored encrypted and never returned again by the list endpoint.
- Signed deliveries. Each delivery is a JSON POST carrying x-signaldeck-timestamp (Unix seconds) and x-signaldeck-signature headers. The signature is a hex-encoded HMAC-SHA256 of {timestamp}.{raw request body}, keyed with your whsec_ signing secret. Recompute it over the exact body bytes, compare in constant time, and reject timestamps more than five minutes old.
- Retries with a fixed backoff. A network error or non-2xx response marks the delivery as retrying, with the next attempt 30 seconds later. The queue allows up to 8 attempts before the job moves to a dead-letter queue.
- Delivery history. GET /api/v1/webhooks lists your endpoints with their five most recent deliveries, including status, attempt count, next attempt time, and the last error.
- Test deliveries. POST /api/v1/webhooks/:id/test sends a signed webhook.test delivery to the endpoint and records it in that endpoint's delivery history.
Webhook routes in the public API.#
All four routes need the webhooks:write scope on an API key, plus the matching permission for the caller's role.
- GET /webhooks. List endpoints and their recent deliveries. Signing secrets are never included.
- POST /webhooks. Create an endpoint. Returns the endpoint and its signing secret, once.
- POST /webhooks/:id/test. Record a webhook.test delivery. Draws on the webhook rate-limit bucket of 300 requests per minute.
- DELETE /webhooks/:id. Disable the endpoint. The endpoint and its delivery history are kept, but no further deliveries are sent.
What happens to each delivery.#
- One delivery per endpoint and event. Deliveries are idempotent on the endpoint and event ID, so a retried job adds an attempt instead of a second delivery.
- Disabled endpoints are skipped. A delivery to a missing or disabled endpoint fails immediately with a clear reason instead of being retried.
- Pause switch. Operators can stop webhook delivery for one organization or everywhere with a kill switch. While it is on, deliveries are not sent.
- Plan limits. Webhook deliveries per month: Starter: not included, Agency: not included, Scale: 100,000, Command: 500,000, Enterprise: custom.
What webhooks do not do yet.#
There is no published catalog of product events such as post or approval changes, no replay of past deliveries from the API, and no separate delivery ID header. This page will list them when they ship.
Questions#
- Which events can I subscribe to?
- You can store a list of event names on each endpoint, but SignalDeck does not publish a product event catalog yet. The documented event today is webhook.test.
- What's the retry budget?
- Up to 8 attempts. A failed attempt schedules the next one 30 seconds later, and a job that keeps failing moves to a dead-letter queue.
- Can I see the signing secret again?
- No. It is returned once when the endpoint is created and stored encrypted. Create a new endpoint if you lose it.
- Can I create a test delivery?
- POST /api/v1/webhooks/:id/test sends a signed webhook.test delivery to the endpoint, and it appears in the endpoint's delivery history.
- Which plans include webhooks?
- Webhook deliveries are counted per month: Starter: not included, Agency: not included, Scale: 100,000, Command: 500,000, Enterprise: custom.