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
You should see a 201 holding secret, shown once. Keep it. Subscribing again with the same settings answers "existing": true and no secret.
| Key | Means |
|---|---|
url | https, public, with no credentials in it, 8 to 2,000 characters. Otherwise 422 url_refused |
when | For endpoint.changed, which it requires: which fields, and optionally which values with is. Up to 20 |
events | What to send. See below |
You can have up to 10 webhooks. Read-only tokens may subscribe, and delete, rotate and test their own.
| Route | Does |
|---|---|
GET /v1/endpoints/{name}/webhooks | Lists 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}/test | Sends webhook.test now and answers with what your server said. 20 an hour |
POST .../webhooks/{id}/rotate | Starts a new secret |
POST .../webhooks/{id}/resume | Starts a paused webhook again |
POST .../webhooks/{id}/deliveries/{delivery_id}/resend | Sends one delivery again |
Choose events
type | Sent when |
|---|---|
endpoint.changed | A sure reading differs from the last sure one |
endpoint.quality_changed | A field has had no sure value for an hour, or came back after that |
alert.opened, alert.closed | An alert opens or closes |
alert.handled, alert.shelved, alert.escalated | Someone claims or shelves it, or it escalates |
log_entry.created, log_entry.read | A scheduled log entry is made, or a person settles it |
webhook.test | You asked for a test |
Unsure readings are never sent as endpoint.changed, so your app sees only values it can act on.
| Key | Means |
|---|---|
alert | started, ended or null: what this did to an alert |
late | Heard more than a minute after it was observed |
superseded | A newer reading already differs. Don’t act on this one |
clock | unsynced 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.
| Header | Holds |
|---|---|
webhook-id | The delivery’s ID. The same on every retry, so use it to ignore repeats |
webhook-timestamp | Unix seconds, set on each attempt |
webhook-signature | v1,<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_.
Sign the raw bytes you received. Parsing the JSON and serializing it again changes them, and the signature fails.
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 answers | Dialect |
|---|---|
| 2xx | Done |
| 5xx, 3xx, 408, or nothing | Uses the whole schedule |
429 or 503 with Retry-After | Waits that long, up to 1 hour |
| 410 | Fails it at once and pauses the webhook |
| Other 4xx | Gives up after 3 attempts |
- If every attempt fails for 5 days, the webhook pauses,
paused_atis 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
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).