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

Headersocotra-signature: t=<unix ms>,v1=<hex>[,v1=<hex>...]
AlgorithmHMAC-SHA256, lowercase hex
Signed contentthe t string exactly as sent, ., then the raw body bytes
Keythe endpoint secret, as UTF-8 bytes (not decoded)
Sent whenthe 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_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/, 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 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). 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):

EventTriggered when
policy.account.createAn account is created
policy.quote.issueA quote is issued
policy.quote.acceptA quote is accepted
billing.invoice.generateAn invoice is generated
billing.payment.createA payment is created
document.readyA 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

Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →