Daftarkan webhook

Mendaftarkan webhook

Daftarkan alamat https publik dan peristiwa yang diinginkan. Rahasia tanda tangan (whsec_…) hanya ditampilkan dalam respons ini. Satu aplikasi bisa punya hingga 10 webhook.

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

Peristiwa

Sofia mengirim setiap peristiwa dengan POST dalam format JSON { id, type, createdAt, data }, dengan header Sofia-Event-Id, Sofia-Event-Type, dan Sofia-Signature. Hanya postingan yang dibuat oleh aplikasi Anda yang diumumkan.

Memverifikasi tanda tangan

Sofia-Signature bernilai t=<unix time>,v1=<hex>, dengan v1 adalah HMAC-SHA256 dari <t>.<raw body> menggunakan rahasia Anda. Verifikasi pada isi mentah, dan tolak stempel waktu yang lama:

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

Pengiriman dan percobaan ulang

• Respons 2xx menyampaikan peristiwa. Respons lain apa pun, pengalihan (tidak pernah diikuti), atau 10 detik tanpa respons memicu percobaan ulang setelah 1 menit, 5 menit, 30 menit, dan 2 jam, hingga 5 kali percobaan.
• Peristiwa yang sama bisa datang dua kali: deduplikasi berdasarkan Sofia-Event-Id.
• Balas dengan cepat dan proses peristiwanya setelahnya.