Webhooks overview

Marlin sends signed HTTP POST requests to your endpoint whenever billable events occur, so your backend stays in sync in real time.

Marlin uses webhooks to push event notifications to your server. When something meaningful happens — an invoice is paid, a subscription is canceled, a payment is confirmed — Marlin sends an HTTP POST request to the URL you register in the dashboard. Your handler receives the event, verifies its authenticity, and acts on it.

Webhook payload structure

Every webhook request body is a JSON-serialized WebhookEvent object.

interface WebhookEvent<T = unknown> {
  id: string;          // Unique event ID, e.g. "evt_01j..."
  object: "event";     // Always "event"
  type: WebhookEventType; // e.g. "invoice.paid"
  data: T;             // Event-specific payload (see Events reference)
  createdAt: string;   // ISO 8601 timestamp
}

The data field contains the full resource object relevant to the event — an Invoice, Subscription, Customer, or payment record. See Webhook event types for the shape of each data payload.

The marlin-signature header

Marlin signs every webhook request with HMAC-SHA256. The signature is sent in the marlin-signature request header using the format:

marlin-signature: t=<unix_timestamp>,v1=<hmac_hex>

• t — Unix timestamp (seconds) of when the event was sent
• v1 — HMAC-SHA256 hex digest of <timestamp>.<raw_body> using your webhook secret

You must verify this header before processing any event. See Verify webhook signatures for step-by-step instructions and code examples.

Set up a webhook endpoint

1. Add your endpoint URL in Settings

   In the Marlin dashboard, go to Settings → Webhooks and enter the public HTTPS URL of your handler.

2. Copy your webhook secret

   After saving the URL, copy the webhook signing secret displayed on the page. It starts with whsec_. Store it as an environment variable — you will not be able to view it again.

3. Deploy a handler that verifies the signature

   Your endpoint must read the raw request body (not parsed JSON) and validate the marlin-signature header before processing the event. Use the verifyWebhook helper from @marlin/sdk or implement HMAC verification manually. See Verify webhook signatures.

4. Return a 2xx response to acknowledge

   Respond with any HTTP status in the 200–299 range immediately after verifying the event. You can process the event asynchronously — Marlin only cares that you acknowledged receipt.

Always return a 2xx status code as quickly as possible. If your endpoint returns a non-2xx response or does not respond within the timeout window, Marlin treats the delivery as failed and schedules a retry. Long-running processing should happen asynchronously after you send the acknowledgment response.

Marlin retries failed deliveries with exponential backoff. You can inspect the delivery history and retry status for any event under Settings → Webhooks → Deliveries in the dashboard.