Webhooks

Register a webhook

Register a public https address and the events you want. The signing secret (whsec_…) is shown only in this answer. An application holds up to 10 webhooks.

curl -X POST https://api.sofia-post.com/api/v1/webhooks \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://app.example.com/hooks/sofia","events":["post.published","post.failed"]}'

Events

Sofia posts each event as JSON { id, type, createdAt, data }, with the headers Sofia-Event-Id, Sofia-Event-Type and Sofia-Signature. Only the posts your application created are announced.

Verify the signature

Sofia-Signature is t=<unix time>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> with your secret. Verify it on the raw body, and refuse an old timestamp:

import { createHmac, timingSafeEqual } from 'node:crypto';

const isSignedBySofia = (header, rawBody, secret) => {
  const parts = Object.fromEntries(
    (header ?? '').split(',').map((part) => part.trim().split('=', 2)),
  );
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || typeof parts.v1 !== 'string') return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
};

Delivery and retries

• A 2xx answer delivers the event. Any other answer, a redirect (never followed) or 10 seconds of silence sends it again after 1 minute, 5 minutes, 30 minutes and 2 hours, up to 5 attempts.
• The same event may arrive twice: deduplicate on Sofia-Event-Id.
• Answer fast and process the event afterwards.

POST /v1/webhooks/{id}/test sends a webhook.test event, signed like the others.