Webhooks

When to use webhooks

If your team needs to react to conversions in real time — pipe them into a CRM, fire a Slack message when a publisher drives a sale, sync earnings to internal accounting — webhooks are the shortest path. For one-off lookups, the dashboard is still faster.

Setup

1. Open Dashboard → Settings → Webhooks.
2. Click Add endpoint and paste the HTTPS URL that should receive events. Optional label so you can tell multiple endpoints apart (“Slack”, “Zapier”, “Internal CRM”).
3. Copy the signing secret — shown once, only at creation. Store it the same way you store API keys.

Endpoints fire from the moment you create them. Disable an endpoint to pause deliveries without losing the secret or history.

Event reference

Payload shape

Every event ships the same envelope. The data object varies by event type.

{
  "event": "conversion.approved",
  "id": "conv_01HXY...",
  "occurredAt": "2026-06-04T12:34:56.789Z",
  "data": {
    "brandId": "brand_...",
    "publisherOrgId": "org_...",
    "channelId": "ch_...",
    "orderRef": "ORDER-12345",
    "orderValueCents": 19999,
    "currency": "EUR",
    "commissionCents": 1600,
    "overrideCents": 560
  }
}

The id field is stable per event source (e.g. the conversion id), so you can dedupe if your endpoint receives the same delivery twice during a retry.

Verifying the signature

Every request carries an x-adryse-signature header of the form sha256=<hex>, where the hex value is HMAC-SHA-256 of the raw request body using your signing secret. Reject any request whose signature doesn’t match — that’s the only way to know it came from Adryse.

// Node.js example
import { createHmac, timingSafeEqual } from "node:crypto";

function verifyAdryseSignature(rawBody, header, secret) {
  const sent = header.replace(/^sha256=/, "");
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(sent, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Other headers

• x-adryse-event — the event type, same value as event in the body. Useful for routing without parsing JSON.
• x-adryse-delivery — unique per delivery attempt. Log it for support requests.

Retries

We expect a 2xx response within 10 seconds. Anything else — non-2xx, timeout, network error — schedules a retry. Backoff is 1 min, 10 min, 1 h, 4 h across up to four attempts. After that the delivery is marked failed and we stop trying. Re-queue from Settings → Webhooks → Delivery log.

Your endpoint must therefore be idempotent. Use the event id field plus your own seen-set if you need to guarantee at-most-once processing.

Delivery log

Every attempt — successful or not — is recorded with the response code, response body (truncated), duration, and retry schedule. Filter by event type or endpoint to investigate a specific integration.

Rotating the secret

Delete the endpoint and recreate it with a fresh URL or label. The old secret stops working immediately. We don’t support in-place rotation today — drop us a note if this gets in your way.

Troubleshooting

I’m not receiving any events

Check the delivery log — if deliveries are marked delivered but you’re not seeing them, your endpoint accepted the POST but routed it somewhere unexpected. If they’re marked failed, the response code and body in the log will tell you why.

Signatures keep failing

Verify against the raw request body, not the parsed JSON. Confirm you’re using the secret tied to the endpoint that fired — each endpoint has its own.

Duplicate deliveries

Expected during retries when your endpoint times out near the 10-second mark — we treat slow responses as failures and retry. Dedupe on the event id.