Webhooks
Details
Stable integration habits: avoid double processing, understand retries, and monitor status.
Failures and good practices
Three habits prevent most production issues:
Reply with 2xx when OK
HTTP 2xx means you accepted the delivery; Alocis does not schedule further attempts for that fact after a 2xx. Only return 2xx after validating the token and being ready to process (or queue) the event.
Validate the token
Each POST includes the account token in the token field (whtok_ prefix). Compare it with the value from the dashboard before granting access or running automations. If it is missing or wrong, return an error (for example 401) and do not run sensitive actions.
Avoid processing twice
Each delivery has a unique id (whdlv_ in the JSON or the X-Webhook-Id header). Automatic retries reuse the same id and the same body recorded on the first attempt — use that id as a deduplication key.
Temporary errors (timeout, 408, 429, 5xx) are retried within a 24-hour window from the first attempt, with up to 8 attempts at 1 min, 5 min, 15 min, 1 h, 4 h, and 12 h intervals. Other 4xx responses are final failures. See the table below.
Idempotency
Idempotency means if the same delivery arrives again, your system should not repeat the side effect (duplicate access, duplicate order, etc.).
- Use the delivery id (JSON id or X-Webhook-Id header, whdlv_ prefix) as a deduplication key.
- Automatic retries reuse the same id and the same business payload snapshot from the first attempt.
Retries and failures
Temporary failures are retried within a 24-hour window from the first attempt, up to 8 attempts, with delays of 1 min, 5 min, 15 min, 1 h, 4 h, and 12 h (the last uses remaining window time).
| HTTP | Meaning |
|---|---|
2xx | Delivery accepted; no further attempts for this fact. |
408, 429, 5xx | Temporary error — another attempt is scheduled within the window. |
4xx (demais) | Permanent error — delivery is marked failed with no further attempts. |
| Timeout or connection | Treated as temporary (same policy as 5xx). |
Paused or removed endpoints do not receive new events; in-flight deliveries follow retry policy until accepted or the window ends.
Dashboard status
Under Add-ons → Webhook → Deliveries you see accepted, failed, or retrying status, attempt count, and a redacted body for debugging. Paused destinations do not receive new events.
On retries, Alocis resends the same snapshot stored on the first attempt — the payload describes state at fact time, not the resource’s current state.