Gareth Wilson Gareth Wilson

Guide to Socotra Webhooks: Features and Best Practices

Published


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

FeatureDetails
Signaturehex HMAC-SHA256
Signature headersocotra-signature
BodyJSON
Event routingBody field type

Events and payloads

EventTriggered WhenCommon Use Cases
policy.account.createAn account is createdSync the customer to a CRM
policy.quote.issueA quote is issuedStart fulfilment, notify the producer
policy.quote.acceptA quote is acceptedKick off underwriting or payment
billing.invoice.generateAn invoice is generatedSend the invoice, update ledgers
billing.payment.createA payment is createdReconcile payments
document.readyA generated document is readyFetch 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:

FieldMeaning
locatorIdentifier of the event
requestIdThe request that caused it
userLocatorThe user behind that request
timestampWhen the event happened
typeEvent name, used for routing
dataType-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 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 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 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.