Descope Webhooks Skill

Descope (CIAM / auth platform) streams audit logs to your API through the Audit Webhook connector. Each request is an HTTP POST whose body is a JSON array of up to 100 audit events, delivered in batches a few minutes after the actions happen. This skill covers the Audit Webhook connector only; Flow HTTP connectors expect a synchronous response body and are not covered.

When to Use This Skill

• How do I receive Descope webhooks / audit events?
• How do I verify the x-descope-webhook-s256 signature?
• How do I handle batched Descope audit events like LoginSucceed or UserModified?
• Why is my Descope webhook signature verification failing?
• Why does my Descope webhook handler receive an array instead of one event?

Verification (core)

If you set an HMAC Secret on the connector, Descope sends x-descope-webhook-s256: the base64 HMAC-SHA256 of the JSON string it posts, keyed with that secret. The secret is optional on the connector, so set one, or anyone can post to your endpoint. Verify against the raw body bytes (not re-serialized JSON) and compare in constant time.

const crypto = require('crypto');

function verifyDescopeSignature(rawBody, signatureHeader, secret) {
  if (!rawBody || !signatureHeader || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
  const received = Buffer.from(signatureHeader);
  if (received.length !== expected.length) return false; // timingSafeEqual needs equal length
  return crypto.timingSafeEqual(received, Buffer.from(expected));
}

// Express: read bytes for any Content-Type so the signature matches
app.post('/webhooks/descope', express.raw({ type: '*/*' }), (req, res) => {
  const ok = verifyDescopeSignature(req.body, req.get('x-descope-webhook-s256'), process.env.DESCOPE_WEBHOOK_SECRET);
  if (!ok) return res.status(400).send('Invalid signature');
  const events = JSON.parse(req.body.toString('utf8')); // array of audit events
  // ...
});

There is no timestamp or ID header, so rely on idempotency for replay protection. Return 2xx only after you have processed the batch; Descope treats any 2xx as delivered and won't resend.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

The event type is the top-level action string. Match it exactly: most are un-spaced, but a few contain a literal space.

For the full list, see Descope audit events.

Payload Shape

Fields are camelCase: action, actorId, userId, projectId, loginIds, occurred (epoch milliseconds, a number), occurred_formatted (RFC 3339), device, method, geo, remoteAddress, tenants (may be null), data (open map). There is no event ID, so derive an idempotency key from fields such as action + userId + occurred.

Environment Variables

# The HMAC Secret you entered on the Audit Webhook connector
DESCOPE_WEBHOOK_SECRET=your_hmac_secret_here

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 descope --path /webhooks/descope

Reference Materials

• references/overview.md - Audit Webhook connector, payload, delivery behavior, common events
• references/setup.md - Configure the connector in the Descope Console
• references/verification.md - Signature verification details and gotchas