Webhooks

Get a signed request when a value changes or an alert moves, and verify it.

Give Dialect a URL and it posts to it when something happens, so you don’t have to poll. At the end your server gets signed requests it can check.

Subscribe

Subscribe to an endpoint

You should see a 201 holding secret, shown once. Keep it. Subscribing again with the same settings answers "existing": true and no secret.

KeyMeans
urlhttps, public, with no credentials in it, 8 to 2,000 characters. Otherwise 422 url_refused
whenFor endpoint.changed, which it requires: which fields, and optionally which values with is. Up to 20
eventsWhat to send. See below

You can have up to 10 webhooks. Read-only tokens may subscribe, and delete, rotate and test their own.

RouteDoes
GET /v1/endpoints/{name}/webhooksLists them, with failing_since, paused_at and the 5 latest deliveries
DELETE /v1/endpoints/{name}/webhooks/{id}Removes it, and drops what’s waiting to send
POST .../webhooks/{id}/testSends webhook.test now and answers with what your server said. 20 an hour
POST .../webhooks/{id}/rotateStarts a new secret
POST .../webhooks/{id}/resumeStarts a paused webhook again
POST .../webhooks/{id}/deliveries/{delivery_id}/resendSends one delivery again

Choose events

typeSent when
endpoint.changedA sure reading differs from the last sure one
endpoint.quality_changedA field has had no sure value for an hour, or came back after that
alert.opened, alert.closedAn alert opens or closes
alert.handled, alert.shelved, alert.escalatedSomeone claims or shelves it, or it escalates
log_entry.created, log_entry.readA scheduled log entry is made, or a person settles it
webhook.testYou asked for a test

Unsure readings are never sent as endpoint.changed, so your app sees only values it can act on.

Body of endpoint.changed
KeyMeans
alertstarted, ended or null: what this did to an alert
lateHeard more than a minute after it was observed
supersededA newer reading already differs. Don’t act on this one
clockunsynced when the gateway’s clock makes observed_at unreliable

endpoint.quality_changed tells you the camera can’t currently answer, which endpoint.changed can’t: it fires only on sure readings. when is optional and limits it to those fields. Its data has state: no_sure_value, sure, or ended if the endpoint stopped. fault is dialect when reads are failing on our side, so there’s nothing for you to fix.

An alert event’s data holds the record from See alerts, with alert_id as its ID and again on a repeat. A log event’s holds webhook_id, endpoint and entry.

Verify the signature

Every request has these headers. They follow Standard Webhooks, so its libraries verify them too.

HeaderHolds
webhook-idThe delivery’s ID. The same on every retry, so use it to ignore repeats
webhook-timestampUnix seconds, set on each attempt
webhook-signaturev1,<base64>. During a rotation, two of them separated by a space

The signature is HMAC-SHA256 of {id}.{timestamp}.{body}, keyed with the base64-decoded part of your secret after whsec_.

Verify a signature in Python

The time check guards against replays. Five minutes is the common choice.

Answer deliveries

Answer with a 2xx within 10 seconds. Do slow work after answering. Requests carry User-Agent: Dialect-Webhooks/1, and redirects aren’t followed.

A failed delivery is retried after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, then every 10 hours, with some jitter: 12 attempts over about 3 days.

Your server answersDialect
2xxDone
5xx, 3xx, 408, or nothingUses the whole schedule
429 or 503 with Retry-AfterWaits that long, up to 1 hour
410Fails it at once and pauses the webhook
Other 4xxGives up after 3 attempts
  • If every attempt fails for 5 days, the webhook pauses, paused_at is set and administrators are emailed. Resume it when you’ve fixed it.
  • Deliveries go out in order, but a retry can arrive after a later one. Order by observed_at, not by arrival.
  • Finished deliveries are kept for 7 days.
  • If the access of whoever made the webhook is revoked, nothing is sent.

Rotate the secret

Rotate a secret

The answer holds the new secret. For 24 hours, each request carries both signatures, so you can switch with no gap. retiring_secret_until says when the old one stops. Only the webhook’s maker or a workspace administrator can rotate it (403 not_maker).

Next steps