# Descope Webhooks

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.

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/descope-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/descope-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/descope-webhooks/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.

| `action` | Description |
| --- | --- |
| `LoginSucceed` | A user logged in (`method` is `Impersonate` if impersonated) |
| `LoginFailed` | Login failed; reason in `data.error_message` |
| `UserCreated` | A user was created |
| `UserModified` | A user was modified; details in `data.Change` |
| `UserDeleted` | A user was deleted |
| `Change Password` | A user's password was changed (note the space) |
| `FlowUpdated` | An authentication flow was modified |
| `ProjectSettings` | Project settings were modified |

> **For the full list**, see [Descope audit events](https://docs.descope.com/audit-trails-and-integrations/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

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

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/descope-webhooks/references/overview.md) - Audit Webhook connector, payload, delivery behavior, common events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/descope-webhooks/references/setup.md) - Configure the connector in the Descope Console
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/descope-webhooks/references/verification.md) - Signature verification details and gotchas