Einen Webhook registrieren

Einen Webhook registrieren

Registriere eine öffentliche https-Adresse und die gewünschten Ereignisse. Das Signaturgeheimnis (whsec_…) wird nur in dieser Antwort angezeigt. Eine Anwendung kann bis zu 10 Webhooks haben.

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"]}'

Ereignisse

Sofia sendet jedes Ereignis per POST im JSON-Format { id, type, createdAt, data }, mit den Headern Sofia-Event-Id, Sofia-Event-Type und Sofia-Signature. Nur die Beiträge, die von deiner Anwendung erstellt wurden, werden gemeldet.

Die Signatur prüfen

Sofia-Signature hat den Wert t=<unix time>,v1=<hex>, wobei v1 der HMAC-SHA256 von <t>.<raw body> mit deinem Geheimnis ist. Prüfe sie über den rohen Body und lehne einen alten Zeitstempel ab:

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

Zustellung und neue Versuche

• Eine 2xx-Antwort stellt das Ereignis zu. Jede andere Antwort, eine Weiterleitung (der nie gefolgt wird) oder 10 Sekunden ohne Antwort lösen einen neuen Versuch nach 1 Minute, 5 Minuten, 30 Minuten und 2 Stunden aus, bis zu 5 Versuche.
• Dasselbe Ereignis kann zweimal ankommen: Entdoppele über Sofia-Event-Id.
• Antworte schnell und verarbeite das Ereignis danach.