# Socotra Webhooks

[Socotra](https://www.socotra.com) is an insurance policy administration platform.
Its webhooks push the same events as its Event Stream (accounts, quotes, policy
transactions, billing, documents, tasks, FNOL, producers and your own `custom.*`
events) to endpoints you create through the Webhook API. Each delivery is an
`EventResponse` (`locator`, `requestId`, `userLocator`, `timestamp`, `type`, `data`).

## When to Use This Skill

* How do I receive Socotra webhooks?
* How do I verify the Socotra `socotra-signature` header?
* Why is my Socotra webhook signature verification failing?
* How do I handle `policy.quote.issue`, `policy.account.create` or `billing.invoice.generate` events?
* What do `hmacEnabled` and `tag` do on a Socotra webhook?

## Setup Note (Hookdeck)

Turn on HMAC (hmacEnabled) for the Socotra endpoint and leave its tag unset. With a tag, Socotra signs a different string and deliveries fail verification.

## Verification (core)

|  |  |
| --- | --- |
| Header | `socotra-signature: t=<unix ms>,v1=<hex>[,v1=<hex>...]` |
| Algorithm | HMAC-SHA256, lowercase hex |
| Signed content | the `t` string exactly as sent, `.`, then the **raw body bytes** |
| Key | the endpoint `secret`, as UTF-8 bytes (not decoded) |
| Sent when | the endpoint has `hmacEnabled` |

Accept the delivery if **any** `v1=` entry matches. Ignore other keys such as `v0`.
A header with no `t=` or no `v1=` fails. Respond `401` for a missing, malformed or
mismatched signature.

```javascript
const crypto = require('crypto');

function verifySocotra(rawBody, header, secret) {   // rawBody: Buffer
  const parts = (header || '').split(',').map((p) => p.trim());
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  const sigs = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
  if (!t || sigs.length === 0) return false;

  const expected = crypto.createHmac('sha256', secret)
    .update(Buffer.concat([Buffer.from(`${t}.`), rawBody])).digest();

  return sigs.some((sig) =>
    // check length + alphabet before decoding: Buffer.from(x, 'hex') drops bad characters
    /^[0-9a-fA-F]{64}$/.test(sig) &&
    crypto.timingSafeEqual(Buffer.from(sig.toLowerCase(), 'hex'), expected));
}

```

Python: `hmac.compare_digest(bytes.fromhex(sig), hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).digest())`, after checking `sig` is 64 hex characters.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/socotra-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/socotra-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/socotra-webhooks/examples/fastapi/).

## Gotchas

* **Raw body.** Verify the exact bytes before parsing. Express: `express.raw({ type: '*/*' })`; Next.js: `await request.arrayBuffer()`; FastAPI: `await request.body()`.
* **Use `t` as a string.** Never parse it to a number and re-format it. It is Unix **milliseconds**.
* **No tag.** A tagged endpoint sends `,tag=<tag>` and signs `{t}.{body}.{tag}`. Hookdeck cannot verify that, so leave the tag unset.
* **Timestamp window is off by default.** Hookdeck retries and replays resend the original timestamp, so a fixed window rejects legitimate deliveries. The examples offer an opt-in `SOCOTRA_WEBHOOK_TOLERANCE_SECONDS` (unset or `0` = off) for direct deliveries.
* **Any HTTP method.** Socotra's docs don't name the method. If you use Hookdeck, allow the method the sender uses on the source ([custom methods](https://hookdeck.com/docs/sources#custom-methods)). The examples accept GET, POST, PUT, PATCH and DELETE, verify first for every method, and treat a missing body as empty bytes (a verified bodyless request gets `200`).
* **Retries are opt-in.** The default failure handling makes no retries; delivery times out after 10 000 ms. Respond quickly and be idempotent.

## Webhook Events (`type`)

Dispatch on the body's `type` field. A selection (the Event Definitions page lists all of them):

| Event | Triggered when |
| --- | --- |
| `policy.account.create` | An account is created |
| `policy.quote.issue` | A quote is issued |
| `policy.quote.accept` | A quote is accepted |
| `billing.invoice.generate` | An invoice is generated |
| `billing.payment.create` | A payment is created |
| `document.ready` | A generated document is ready |

Handle the ones you need and log the rest (including `custom.*` events).

## Environment Variables

```bash
SOCOTRA_WEBHOOK_SECRET=your_socotra_webhook_secret   # the endpoint `secret` (8-64 alphanumerics/underscores)
# SOCOTRA_WEBHOOK_TOLERANCE_SECONDS=300             # optional replay window; unset or 0 = off

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/socotra-webhooks/references/overview.md): Socotra webhook concepts, events, delivery and failure handling
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/socotra-webhooks/references/setup.md): Create the webhook, enable HMAC, point it at Hookdeck
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/socotra-webhooks/references/verification.md): Signature details, gotchas, debugging