Webhooks

Register an HTTPS endpoint with POST /webhooks and a list of events (default post.published, post.failed, post.pending_approval). Each delivery is a POST with the body {id, event, createdAt, data}:

WhatsApp numbers bought through Postgale add phone_number.* events; see the WhatsApp guide.

Signatures and retriesCopy Anchor Link

• X-SocialAPI-Signature: hex HMAC-SHA256 of `${X-SocialAPI-Timestamp}.${body}` with the webhook secret.
• X-SocialAPI-Timestamp (unix seconds), X-SocialAPI-Event, X-SocialAPI-Delivery (this delivery row).
• X-Idempotency-Key: the original delivery id (also the body id), stable across retries and redeliveries.
• Any non-2xx answer or timeout (10 s) is retried with exponential backoff, up to 6 attempts. Inspect with GET /webhooks/{id}/deliveries, replay with POST /webhooks/deliveries/{deliveryId}/redeliver, check your endpoint with POST /webhooks/{id}/test.
• comment.received, mention.received and message.* need the account subscribed to Meta webhooks (POST /accounts/{id}/webhook-subscription). Comments the account itself posted are not reported.

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

const seen = new Set<string>(); // use a persistent store in production

export async function POST(request: Request) {
  const body = await request.text(); // the raw body, before JSON.parse
  const timestamp = request.headers.get('x-socialapi-timestamp') ?? '';
  const signature = request.headers.get('x-socialapi-signature') ?? '';

  // Reject stale or replayed requests (5-minute tolerance).
  if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300)) return new Response('stale', { status: 400 });

  const expected = Buffer.from(createHmac('sha256', process.env.POSTGALE_WEBHOOK_SECRET!).update(`${timestamp}.${body}`).digest('hex'));
  const actual = Buffer.from(signature);
  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return new Response('bad signature', { status: 401 });

  // Retries and redeliveries carry the same key: process each event once.
  const key = request.headers.get('x-idempotency-key')!;
  if (seen.has(key)) return new Response('ok');
  seen.add(key);

  const { event, data } = JSON.parse(body);
  // ... handle event
  return new Response('ok');
}

EndpointsCopy Anchor Link

Inbound Meta webhooksCopy Anchor Link

For operators configuring the Meta apps of a Postgale instance. Set each product's callback URL to:

• https://postgale.com/api/webhooks/meta/instagram
• https://postgale.com/api/webhooks/meta/facebook
• https://postgale.com/api/webhooks/meta/threads
• https://postgale.com/api/webhooks/meta/whatsapp

Then:

• GET performs the verification handshake: hub.verify_token must equal META_WEBHOOK_VERIFY_TOKEN, and hub.challenge is echoed.
• POST requires a valid X-Hub-Signature-256 made with that product's app secret (INSTAGRAM_CLIENT_SECRET, FACEBOOK_APP_SECRET, THREADS_APP_SECRET; WhatsApp: WHATSAPP_APP_SECRET, then FACEBOOK_APP_SECRET); otherwise 401.
• Events are deduplicated, stored as inbound events (GET /inbox/events) and forwarded as comment.received / mention.received. Messaging events are stored as conversations and messages and forwarded as message.*.