Webhooks

Driftstack delivers event notifications to your HTTPS endpoint as they happen. Use webhooks to react to session lifecycle, egress, challenge, profile-save, payment, and key-revocation events without polling.

Event types

test.ping is an additional event type that exists only for the POST /v1/webhooks/<id>/test endpoint; it bypasses subscriptions, so you don't list it under events when creating an endpoint.

Each account can have up to 10 active endpoints. Mint as many narrow-purpose endpoints as you need rather than one mega-endpoint that fans out — easier to retire individual integrations later.

Creating an endpoint

POST /v1/webhooks
Authorization: Bearer ds_live_…
Content-Type: application/json

{
  "url": "https://yourapp.com/driftstack-webhook",
  "events": ["session.completed", "session.failed"],
  "description": "Production listener"
}

→ 201 Created
{
  "id": "whk_…",
  "secret": "whsec_…",          ← shown ONCE; copy it now
  "secret_prefix": "whsec_xxxx",
  "url": "https://yourapp.com/driftstack-webhook",
  "events": ["session.completed", "session.failed"],
  "description": "Production listener",
  "active": true,
  "consecutive_failures": 0,
  "delivery_counts": { "pending": 0, "delivered": 0, "failed": 0, "dlq": 0 },
  "created_at": "2026-05-12T12:00:00.000Z",
  …
}

Important: the secret is shown once in the create response and never again. Store it in your config / secret manager. If you lose it, rotate via POST /v1/webhooks/<id>/rotate-secret. Subsequent GET /v1/webhooks/<id> responses include only secret_prefix (first 12 plaintext chars, non-sensitive) for display.

Endpoint URLs MUST be HTTPS. http:// is rejected at registration time.

Delivery payload

Every event arrives as a JSON POST to your endpoint:

POST /driftstack-webhook
Content-Type: application/json
X-Driftstack-Event-Id: <uuid>
X-Driftstack-Event-Type: session.completed
X-Driftstack-Signature: t=1747051200,v1=<hex hmac>

{
  "id": "<uuid>",
  "type": "session.completed",
  "created_at": "2026-05-12T12:00:00.000Z",
  "data": { /* event-specific payload */ }
}

During a secret-rotation grace window the single X-Driftstack-Signature header carries both the new and old HMACs as two comma-separated v1= entries (t=…,v1=<new>,v1=<old>) — see Secret rotation below.

Signature verification

Always verify the signature before trusting the payload — otherwise anyone who guesses your endpoint URL can spoof events.

The header is Stripe-style: X-Driftstack-Signature: t=<unix-seconds>,v1=<hex hmac>. The HMAC is computed as:

hmac = HMAC-SHA256(
  secret,
  <unix-seconds> + "." + <raw request body>
)

The timestamp lives inside the header (the t= component), not in a separate header. There is no X-Driftstack-Emitted-At header: the delivery path sends exactly three X-Driftstack-* headers — Event-Id, Event-Type and Signature.

Server-side verification in Node.js looks like:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(req, secret) {
  const header = req.headers['x-driftstack-signature'];   // 't=…,v1=…'
  const body = req.rawBody;                                // RAW bytes — NOT parsed JSON
  if (typeof header !== 'string' || !body) return false;

  const parts = Object.fromEntries(
    header.split(',').map((p) => {
      const i = p.indexOf('=');
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    }),
  );
  const ts = Number(parts.t);
  const sig = parts.v1;
  if (!ts || !sig) return false;

  // Reject replays — Driftstack signs with the current timestamp;
  // anything older than 5 minutes is almost certainly a replay.
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(`${ts}.${body}`)
    .digest('hex');
  const a = Buffer.from(sig, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Or use the SDK helpers — they handle the parsing, replay window, and previous-secret grace path for you:

• TypeScript / JS: import { verifyWebhookSignature } from '@driftstack/sdk'
• Python: from driftstack import verify_webhook_signature
• Go: driftstack.VerifyWebhookSignature(...)

Retry policy

Driftstack retries non-2xx responses (and timeouts) with backoff. The schedule is fixed:

• After 6 attempts (the initial delivery plus 5 retries), the delivery moves to a dead-letter queue (DLQ). You can requeue from the dashboard or via the admin API.
• After 50 consecutive failures across all deliveries for one endpoint, the endpoint is auto-disabled. You'll see an email + a banner in the dashboard. Re-enable from the dashboard once the receiving service is healthy.
• Request timeout is 10 seconds — slower than that, we consider the delivery failed and back off.

Your endpoint should:

• Return 2xx within 10 seconds.
• Be idempotent — we may retry the same X-Driftstack-Event-Id if our delivery infra retried before getting your response.
• Acknowledge fast + process asynchronously. A 200 response means "I have the payload"; process it on your side after.

Secret rotation

When you suspect a leaked secret (or just for routine hygiene), rotate it:

POST /v1/webhooks/<id>/rotate-secret
Authorization: Bearer ds_live_…

→ 200 OK
{
  "id": "whk_…",
  "secret": "whsec_NEW…",       ← shown ONCE; copy it now
  "secret_prefix": "whsec_yyyy",
  "prev_secret_prefix": "whsec_xxxx",
  "grace_expires_at": "2026-05-13T12:00:00.000Z"
}

During the 24-hour grace window, Driftstack signs every outbound delivery with both secrets inside the single X-Driftstack-Signature header, as two comma-separated v1= entries:

• v1=<new> — signed with the new secret.
• v1=<old> — signed with the old secret.

X-Driftstack-Signature: t=…,v1=<new>,v1=<old>

Your verifier should accept the delivery if either HMAC matches. The SDK helpers do this automatically — they iterate every v1= entry in the one header, so no extra argument is needed. Roll the new secret across your infra at your own pace during the grace window — when it expires, the old v1= entry drops and only the new-secret signature is sent.

Testing

Use the test endpoint to fire a synthetic test.ping event at any active endpoint, bypassing subscription:

POST /v1/webhooks/<id>/test
Authorization: Bearer ds_live_…

→ 202 Accepted
{
  "delivery_id": "wdl_…",
  "event_id": "<uuid>",
  "event_type": "test.ping"
}

The test event arrives at your endpoint with the same headers + signature as a real event. Your endpoint's response is captured so you can debug from the dashboard.

Inspecting deliveries

Per-endpoint delivery log + counts available from the dashboard under Webhooks → <endpoint> → Deliveries, or from GET /v1/webhooks/<id>/deliveries. Failed deliveries surface the response status + first 200 bytes of your endpoint's response body so you can debug.

What to do when something goes wrong

• Signatures don't verify — confirm you're hashing the raw request body, not the parsed JSON. Most frameworks parse the body by default; you need a raw-body middleware ahead of the JSON parser. Also confirm you're reading the timestamp from inside X-Driftstack-Signature (the t= component), not from a separate header.
• Endpoint auto-disabled — fix the receiving service, then re-enable via the dashboard. Past deliveries in DLQ can be requeued.
• Duplicate events — expected. Dedupe on X-Driftstack-Event-Id.
• Missing events — check the endpoint registration includes the event type you're expecting; events only fire to endpoints subscribed to that type.

Support

Questions or trouble integrating? [email protected].