Skip to content

Documentation

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

  1. 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
    1. Admin → Settings → Integrations → Webhooks → Add endpoint
  2. 02

    Verify the signature

    Before trusting a delivery, check its signature with your signing secret. A Node.js example is below.

    • Read t and v1 from the x-eventier-webhook-signature header
    • Compute HMAC SHA-256 over <t>.<raw request body> with the signing secret
    • Compare the hex digest to v1 in constant time
    • Reject the request if they differ, or if t is more than five minutes from your clock
    • Because the timestamp is signed, a captured request cannot be replayed later
    1. x-eventier-webhook-signature: t=<unix seconds>,v1=<hex>
    2. v1 = hex( HMAC-SHA256( key = signing secret, message = "<t>.<raw JSON body>" ) )
  3. 03

    Handle retries

    The same event can arrive more than once. Skip repeats and answer fast.

    • Record x-eventier-event-id and 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
  4. 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

Verify a delivery (Node.js)javascript
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 fieldWhat it holds
x-eventier-webhook-signaturet=<unix seconds>,v1=<hex>; v1 is HMAC SHA-256 of <t>.<raw JSON body>, keyed with the signing secret
x-eventier-eventThe event type in upper case, for example REQUEST_CREATED
x-eventier-event-idThe same for every retry of one event; equal to the body's id field
x-eventier-deliveryThe delivery record; useful when contacting support
eventThe event name in dotted form, for example request.created
occurredAtWhen the event happened, which can be earlier than when it was sent
firedAtautomation.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.isConfidentialtrue for a confidential request: data. on request and approval events, request. on automation.fired