Webhooks

Sorplos tells your systems about every event on your business by posting it to HTTPS endpoints you register. Each delivery is signed, so you can prove it came from us.

Registering an endpoint

In the Insurer Portal, go to Settings → Webhooks, enter your URL and choose the events it should receive. You can register several endpoints — for example one for applications and one for claims. Each endpoint has its own signing secret.

Events

Event	Sent when
`application.submitted`	A paid application is sent to you.
`application.rfi_requested`	An RFI is raised on one of your applications.
`application.approved`	An application is approved — through the API or in the portal.
`application.rejected`	An application is rejected.
`policy.issued`	A policy goes live (or is scheduled to).
`policy.corrected`	A correction creates a new policy version.
`policy.cancelled`	A policy is cancelled.
`claim.reported`	A customer reports a claim on one of your policies.
`claim.approved`	A claim is approved.
`claim.settled`	A claim is paid.
`payment.received`	A premium payment is confirmed.
`payment.failed`	A premium payment fails.
`payment.refunded`	A premium is refunded, e.g. after a rejection.

Payload

Every delivery is a JSON POST with the same envelope. data is the object as it was when the event happened — the same shape the API returns for it.

JSON

{
  "id": "evt_01J8Z4QK7M3T",
  "type": "application.submitted",
  "created_at": "2026-09-14T09:20:05Z",
  "data": {
    "id": "SPL-APP-2026-045",
    "status": "submitted",
    "...": "the full application — see the Applications reference"
  }
}

Header	Value
`X-Sorplos-Event-ID`	The event's id. The same on every retry of the same event.
`X-Sorplos-Event-Type`	The event type, e.g. application.submitted.
`X-Sorplos-Timestamp`	When this delivery was signed, in Unix seconds.
`X-Sorplos-Signature`	Hex HMAC-SHA256 of the timestamp, a dot, and the raw body, keyed with the endpoint's secret.

Verifying signatures

Read the raw request body as bytes — before any JSON parsing changes it.
Compute HMAC-SHA256 of {X-Sorplos-Timestamp}.{raw body} with the endpoint's signing secret, and hex-encode it.
Compare it with X-Sorplos-Signature using a constant-time comparison.
Reject the delivery if the timestamp is more than 5 minutes from your clock.

Node.js

import crypto from "node:crypto";

// rawBody must be the exact bytes received — verify before parsing JSON.
export function verifySorplosSignature(rawBody, headers, secret) {
  const timestamp = headers["x-sorplos-timestamp"];
  const signature = headers["x-sorplos-signature"];
  if (!timestamp || !signature) return false;

  // Reject old deliveries so a captured request can't be replayed.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + ".")
    .update(rawBody)
    .digest();
  const received = Buffer.from(signature, "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Responding and retries

Answer with any 2xx within 10 seconds. Do the real work afterwards, from a queue.
Anything else is retried 3 times, after 1 minute, 5 minutes and 15 minutes. After that the delivery is marked failed, and you can see it in the portal.
An endpoint that keeps failing is paused; resume it from Settings → Webhooks.

Duplicates and ordering

A retry can arrive even after you've processed the first delivery, so store each X-Sorplos-Event-ID you've handled and ignore repeats. Events can also arrive out of order: use created_at, and when the current state matters, fetch it from the API rather than trusting the last event you saw.