Agent skill
Socotra Webhooks Skill
Receive and verify Socotra Insurance Suite webhooks. Use when setting up Socotra webhook handlers, debugging the socotra-signature header (HMAC-SHA256 over {t}.{body}), configuring hmacEnabled and tags, or handling policy, quote, account and billing events such as policy.quote.issue and billing.invoice.generate.
Install this skill
npx skills add hookdeck/webhook-skills --skill socotra-webhooks
Socotra 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-signatureheader? - Why is my Socotra webhook signature verification failing?
- How do I handle
policy.quote.issue,policy.account.createorbilling.invoice.generateevents? - What do
hmacEnabledandtagdo 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.
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_, after checking sig is 64 hex characters.
For complete handlers with tests, see examples/express/, examples/nextjs/, 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
tas 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_(unset orWEBHOOK_ TOLERANCE_ SECONDS 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). 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
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
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 socotra --path /webhooks/socotra
Reference Materials
- references/overview.md: Socotra webhook concepts, events, delivery and failure handling
- references/setup.md: Create the webhook, enable HMAC, point it at Hookdeck
- references/verification.md: Signature details, gotchas, debugging