# Guide to Socotra Webhooks: Features and Best Practices

[Socotra Insurance Suite](https://www.socotra.com) is a policy administration platform for insurers: it holds accounts, quotes, policies and their transactions, billing, documents, tasks and first notice of loss (FNOL). Its webhooks push the same events as the Event Stream to an HTTPS endpoint, so an integration can follow a policy from quote to issue, an invoice from generation to settlement, or a claim from FNOL onwards without polling.

This guide covers how Socotra webhooks are created through the Webhook API, what the `EventResponse` envelope contains, how the `socotra-signature` header is built and why tagged secrets break gateway verification, plus the delivery limits to plan around: a 10-second timeout and no retries unless you configure them.

## What are Socotra webhooks?

A Socotra webhook is a subscription created with a `POST` to the Create Webhook endpoint, naming a URL and the event types to send there. There is no dashboard form for it. Each delivery is an `EventResponse`, the same object the Event Stream returns, so one parser can serve both. The `type` field carries the event name, from a list of 226 documented types plus any `custom.*` types your tenant's configuration defines.

Signing is optional. When `hmacEnabled` is on, Socotra adds a `socotra-signature` header with a millisecond timestamp and a hex HMAC-SHA256 digest. The endpoint's security settings also hold `secureSSL`, which can turn off TLS certificate checks for test endpoints.

## Socotra webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `socotra-signature` |
| Body | JSON |
| Event routing | Body field `type` |

## Events and payloads

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `policy.account.create` | An account is created | Sync the customer to a CRM |
| `policy.quote.issue` | A quote is issued | Start fulfilment, notify the producer |
| `policy.quote.accept` | A quote is accepted | Kick off underwriting or payment |
| `billing.invoice.generate` | An invoice is generated | Send the invoice, update ledgers |
| `billing.payment.create` | A payment is created | Reconcile payments |
| `document.ready` | A generated document is ready | Fetch and deliver the document |

Policy events follow each transaction type through its lifecycle. `policy.quote.*` runs from `create` through `validate`, `price`, `underwrite`, `accept` and `issue`, with `refuse`, `discard` and `reset` as exits, and the same verbs repeat for `policy.change.*`, `policy.cancellation.*`, `policy.flatCancellation.*`, `policy.reinstatement.*`, `policy.renewal.*` and `policy.continuation.*`. Billing covers invoices (`generate`, `settle`, `autopay`, `autopayfailed`), payments (`create`, `post`, `fail`, `reverse` and more), disbursements, holds, write-offs, credit distributions and delinquency (`create`, `lapse`, `settle`).

Outside policy and billing, Socotra lists `document.ready`, `document.failed` and `document.plugin.failed`, `task.*`, `claim.fnol.*`, `contact.*`, `producers.*` (producers, codes, appointments and licences), `moratorium.*` and `migration.*`, plus several `*.numberAssignmentFailed` types. Types defined in your configuration arrive as `custom.*` and won't appear on Socotra's list.

### Event Payload Structure

Every delivery has the same top-level fields:

| Field | Meaning |
| --- | --- |
| `locator` | Identifier of the event |
| `requestId` | The request that caused it |
| `userLocator` | The user behind that request |
| `timestamp` | When the event happened |
| `type` | Event name, used for routing |
| `data` | Type-specific object |

The Event Definitions page names a data schema for each type (account events use `AccountEventData`, which carries `accountLocator`, for example) but publishes no complete delivery body. The one body in the webhook docs, inside the signing sample, has a different envelope and a `login.success` type that isn't on the list, so don't build a parser from it. Capture a real delivery for each type you handle.

## Setting up Socotra webhooks

### Prerequisites

* A Socotra tenant and credentials for the Webhook API
* A public HTTPS endpoint, e.g. `https://example.com/webhooks/socotra`

### How Do I Create a Socotra Webhook?

1. Call the Create Webhook endpoint with the `url` and the event types to send. Include any `custom.*` types by name.
2. In the endpoint's security settings, set a `secret` of 8 to 64 letters, digits or underscores, and turn on `hmacEnabled`.
3. **Leave `tag` unset.**
4. Keep `secureSSL` at `true` for anything other than a throwaway test endpoint.

> 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.

If `hmacEnabled` is off, no `socotra-signature` header is sent and there is nothing to verify. In that case leave verification off on the receiving side, and turn signing on before production traffic.

### Which HTTP Method Does Socotra Use?

Socotra's docs don't name the HTTP method. Hookdeck's Socotra source pre-selects POST without managing the method, so any other method the sender uses must also be allowed on the source. The linked skill examples accept GET, POST, PUT, PATCH and DELETE.

### Optional: Failure Handling

A new webhook makes no retries. To get them, set `failureHandling`: which responses count as failures (`4xx`, `5xx`, specific status codes, `timeout`), 1 to 10 attempts (3 by default once a strategy is set), a linear or exponential interval, and whether to `suspend` the webhook, `divert` failed events to the Diverted Events API or call an `alertEndpoint`. See the skill's [overview](https://github.com/hookdeck/webhook-skills/blob/main/skills/socotra-webhooks/references/overview.md) for the field names.

### Environment Variables

```bash
WEBHOOK_SECRET=your_socotra_webhook_secret

```

### Test a delivery

Start a local receiver and forward requests with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 socotra --path /webhooks/socotra

```

Create a webhook in a test tenant pointing at the CLI's URL, subscribe it to something easy to trigger such as `policy.account.create`, then create an account. Check the method, the `socotra-signature` header and the `data` object before writing handlers.

## Securing Socotra webhooks

Split `socotra-signature` on commas. Take `t` (Unix time in milliseconds) and `v1`, build the message from the `t` text, a dot and the raw body, compute HMAC-SHA256 with the endpoint secret as UTF-8 bytes, and compare the hex digest with `v1` in constant time. A third `tag=` part means the endpoint has a tag and the message ends in `.<tag>`; the verifier below doesn't support that. See the [webhook documentation](https://docs.socotra.com/configuration/general-topics/webhooks).

### Node.js verification

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

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['socotra-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const parts = signature.split(',').map((part) => part.trim());
  const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
  if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
  const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
  const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The handler accepts any method, as the HTTP method is undocumented. It acknowledges an empty body once the signature passes, skips events it has already seen by `locator`, and routes on `type`. A failure inside a handler returns `503`, which only leads to a retry if `failureHandling` covers `5xx`.

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

function createSocotraApp({ seen, remember, handlers }) {
  const app = express();
  app.all('/webhooks/socotra', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
    if (!req.body.length) return res.sendStatus(200);
    let parsed;
    try {
      parsed = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
    const { locator, type, data } = parsed;
    if (!locator || typeof type !== 'string') return res.sendStatus(400);
    try {
      if (await seen(locator)) return res.sendStatus(200);
      if (type.startsWith('custom.')) await handlers.custom?.(type, data);
      else if (handlers[type]) await handlers[type](data);
      else console.log('Unhandled Socotra event', type);
      await remember(locator);
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

```

Socotra documents no tolerance for `t`, and the verifier sets none. Keep it that way if you replay through Hookdeck, since a replay carries the original header. Keep `t` as the string you received: reformatting it as a number would change the signed bytes.

With a Socotra source in Hookdeck, the gateway parses `t` and `v1`, checks the HMAC of `<t>.<body>` against your secret, and answers Socotra with `200` whether or not the check passes. A mismatch is logged as failed verification and isn't delivered onwards. Tagged endpoints always land in that state, which is why the tag has to stay unset.

> **Run Socotra webhooks with confidence.** [Hookdeck Event Gateway](/event-gateway) verifies Socotra's signature, takes each delivery inside the 10-second timeout and retries your service for you, even when the webhook itself has no retry strategy.

## Socotra webhook limitations and pain points

### No retries by default

**The Problem:** An event that hits a timeout or an error on a webhook without `failureHandling` is not sent again.

**Why It Happens:** Socotra's default failure handling has `divert: false`, `suspend: false` and no retry attempts. Retries exist only when you configure them.

**Workarounds:**

* Set `failureHandling` on every production webhook, with `timeout` and `5xx` among the triggers.
* Turn on `divert` so failed events go to the Diverted Events API instead of disappearing.

**How Hookdeck Can Help:** Hookdeck acknowledges Socotra on the first attempt and keeps the event. Retries to your service run on Hookdeck's schedule, and any event can be replayed by hand.

### Tags and gateway verification

**The Problem:** You can't use the `tag` field to name and rotate secrets if a gateway verifies the signature.

**Why It Happens:** A tag adds `.<tag>` to the signed string. Hookdeck's Socotra source signs `<t>.<body>` only.

**Workarounds:**

* Leave `tag` unset and rotate by changing the secret on the Socotra endpoint and the Hookdeck source together.
* Schedule rotation at a quiet time, since deliveries signed with the old secret will fail verification once the source has the new one.

**How Hookdeck Can Help:** Failed verifications are recorded with their headers, so you can see exactly which deliveries landed between the two changes.

### Short timeout

**The Problem:** A slow handler causes failures even when it finishes the work.

**Why It Happens:** Socotra waits 10,000 ms for a response, and a `timeout` failure is only retried if your `failureHandling` includes it.

**Workarounds:**

* Store the event and respond, then do document fetches and downstream calls from a queue.

**How Hookdeck Can Help:** Hookdeck answers well inside the timeout and gives your service its own, longer delivery window.

### Payload shapes are documented by name only

**The Problem:** You have to infer each type's `data` object.

**Why It Happens:** The Event Definitions page lists types and schema names but no example bodies, and `custom.*` types depend on your configuration.

**Workarounds:**

* Save real deliveries from a test tenant as fixtures, one per type you handle.
* Route `custom.*` types to a separate handler that tolerates unknown fields.

**How Hookdeck Can Help:** Hookdeck keeps the full body and headers of every delivery for inspection, and lets you filter or route connections on `type`.

### Unstated method, ordering and sender IPs

**The Problem:** Firewall rules and handler assumptions have nothing to go on.

**Why It Happens:** Socotra's docs don't give the HTTP method, ordering guarantees or egress IP ranges.

**Workarounds:**

* Accept any method on the receiving route and rely on the signature rather than IP allow lists.
* Compare `timestamp` against stored state before applying an update.

**How Hookdeck Can Help:** Hookdeck records the method and headers of every delivery, so the first test event settles the method question, and the source can allow whichever methods Socotra uses.

## Best practices

### Keep the endpoint secure

Turn on `hmacEnabled` and keep `secureSSL` on in production. Store the secret outside source control and use it exactly as set, with no encoding.

### Configure failure handling deliberately

Decide which status codes count as failures, how many attempts to allow and whether to divert, then record the settings alongside the webhook definition so new environments get the same behaviour.

### Deduplicate and check state

Use `locator` to skip events already processed. For policy transactions, check the current status from the `data` object or the API before acting, since the docs make no promise about ordering.

### Subscribe narrowly

There are over 200 types. Subscribe to the ones you handle, and use separate webhooks for unrelated consumers so a slow billing integration doesn't hold up policy work.

## Conclusion

Socotra's webhooks reuse the Event Stream's envelope and offer per-webhook control over signing and failure handling. The trade-off is that the safe settings aren't the defaults: signing and retries both have to be switched on, the tag has to stay off for gateway verification, and payload shapes have to be learned from real traffic.

[Hookdeck Event Gateway](https://hookdeck.com) adds stored deliveries, retries and replay on top of Socotra's opt-in failure handling.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Socotra webhooks reliably in minutes.