Guide to Socotra Webhooks: Features and Best Practices
Socotra Insurance Suite 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?
- Call the Create Webhook endpoint with the
urland the event types to send. Include anycustom.*types by name. - In the endpoint's security settings, set a
secretof 8 to 64 letters, digits or underscores, and turn onhmacEnabled. - Leave
tagunset. - Keep
secureSSLattruefor 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 for the field names.
Environment Variables
WEBHOOK_SECRET=your_socotra_webhook_secret
Test a delivery
Start a local receiver and forward requests with the Hookdeck CLI:
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.
Node.js verification
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.
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 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
failureHandlingon every production webhook, withtimeoutand5xxamong the triggers. - Turn on
divertso 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
tagunset 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
timestampagainst 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 adds stored deliveries, retries and replay on top of Socotra's opt-in failure handling.
Get started with Hookdeck for free and handle Socotra webhooks reliably in minutes.