Webhooks
Send four request events to a URL in your own system. Every payload is signed with HMAC SHA-256 so your receiver can check it came from EvenTier.
- Where
- Admin → Settings → Integrations → Webhooks
- Permission
- MANAGE_INTEGRATIONS
- Updated
- October 2026
Overview
A webhook sends a JSON message to a URL you choose each time an event it subscribes to happens.
You can subscribe to four events: request.created, request.updated, request.resolved and approval.decided.
A status change is delivered as request.updated. Resolving a request sends request.resolved.
Automations can also POST to one endpoint with the Call a webhook action. Those arrive as automation.fired, whatever events the endpoint subscribes to.
Every delivery is signed with the endpoint's signing secret (it starts with whsec_). The secret is generated and shown once, when the webhook is created.
Delivery is at least once. A failed delivery is tried three times a few seconds apart, then retried in the background with exponential backoff.
A 4xx response other than 408, 425 or 429 is treated as permanent and not retried.
Each endpoint on the Webhooks tab lists its five most recent deliveries, with the attempt count and the HTTP status of the last attempt.
Confidential requests are delivered like any other, since an administrator set up the endpoint. Each payload marks them with isConfidential.
If your receiver forwards events somewhere shared, such as a chat channel, skip the ones where isConfidential is true.
Step by step
- 01
Create a webhook
Add an endpoint, choose its events, and copy the signing secret.
- Enter a label and your endpoint URL
- Check the events to subscribe to
- Copy the signing secret now; it is shown only once
- Admin → Settings → Integrations → Webhooks → Add endpoint
- 02
Verify the signature
Before trusting a delivery, check its signature with your signing secret. A Node.js example is below.
- Read
tandv1from thex-eventier-webhook-signatureheader - Compute HMAC SHA-256 over
<t>.<raw request body>with the signing secret - Compare the hex digest to
v1in constant time - Reject the request if they differ, or if
tis more than five minutes from your clock - Because the timestamp is signed, a captured request cannot be replayed later
- x-eventier-webhook-signature: t=<unix seconds>,v1=<hex>
- v1 = hex( HMAC-SHA256( key = signing secret, message = "<t>.<raw JSON body>" ) )
- Read
- 03
Handle retries
The same event can arrive more than once. Skip repeats and answer fast.
- Record
x-eventier-event-idand skip a delivery whose id you have already processed - Return a 2xx right away
- A delivery that times out or gets a 5xx, 408, 425 or 429 is retried with growing delays for about 24 hours
- Any other 4xx answer is final
- To debug failures, check the endpoint's recent deliveries on the Webhooks tab
- Record
- 04
Rotate the secret
The signing secret is shown only when the webhook is created, so rotate it by replacing the endpoint.
- Create a new webhook endpoint with the same URL
- Switch your verifier to the new secret
- Delete the old endpoint
Examples
import crypto from "node:crypto";
// rawBody: the request body exactly as received, before JSON parsing
// header: the x-eventier-webhook-signature header
// secret: the endpoint's signing secret (whsec_...)
function verifyEventierWebhook(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
const t = Number(parts.t);
if (!parts.v1 || !Number.isFinite(t)) return false;
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(parts.t + "." + rawBody)
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(parts.v1, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Delivery headers and fields
Every delivery carries these headers. The last rows are fields in the JSON body.
| Header or field | What it holds |
|---|---|
| x-eventier-webhook-signature | t=<unix seconds>,v1=<hex>; v1 is HMAC SHA-256 of <t>.<raw JSON body>, keyed with the signing secret |
| x-eventier-event | The event type in upper case, for example REQUEST_CREATED |
| x-eventier-event-id | The same for every retry of one event; equal to the body's id field |
| x-eventier-delivery | The delivery record; useful when contacting support |
| event | The event name in dotted form, for example request.created |
| occurredAt | When the event happened, which can be earlier than when it was sent |
| firedAt | automation.fired only: when the rule ran. The payload also has the request's status and priority as they stand when the delivery is made |
| data.isConfidential · request.isConfidential | true for a confidential request: data. on request and approval events, request. on automation.fired |