Webhooks

Overview

Webhooks let Amarsia push event notifications to your application as they happen. When a resource changes, Amarsia sends an HTTP POST request to your configured endpoint with the event payload.

When to use webhooks

Use webhooks when you need to react to events in real time — syncing data to your database, triggering workflows, or updating external systems — without polling the API.

Creating a webhook

Go to Settings → Webhooks → Add endpoint.
Enter your endpoint URL (must be publicly accessible over HTTPS).
Select the event types you want to receive.
Save. Amarsia sends a test event to verify the endpoint is reachable.

Event payload

Every webhook delivers a POST request with a JSON body:

{
  "id": "evt_01j...",
  "type": "resource.created",
  "created_at": "2025-01-01T00:00:00Z",
  "data": {
    "id": "res_01j...",
    "type": "contact",
    "fields": { ... }
  }
}

Verifying signatures

Every webhook request includes an Amarsia-Signature header. Verify this signature to confirm the request is from Amarsia and has not been tampered with.

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Always verify the signature before processing a webhook payload. Skip verification only during local development.

Retries

If your endpoint returns a non-2xx status code, Amarsia retries the delivery up to 5 times with exponential backoff (1m → 5m → 30m → 2h → 8h).