Receive webhook events

Add your endpoint#

1. 1

   Prepare an HTTPS receiver

   Your server must accept POST requests at a public HTTPS URL. Do not put usernames or passwords in the URL. Handle the signed event on your server, not in a browser page.
2. 2

   Choose events

   Open Webhooks, enter Endpoint URLand select events under Send me. Click Add endpoint.
3. 3

   Save the signing secret

   Copy the signing secret when the endpoint is added. It is shown once. Keep it in your receiver’s server-side secret storage and verify incoming requests before using their data.

Choose your events#

Verify and acknowledge deliveries#

Each request contains an event envelope with id, type, createdAt and data. Check X-Lanternaut-Signature using the exact raw body before parsing JSON. The header has the form sha256= followed by a hexadecimal HMAC.

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

function verifyWebhook(rawBody, signature, secret) {
  const expected = 'sha256=' +
    createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = Buffer.from(signature ?? '');
  const calculated = Buffer.from(expected);
  return received.length === calculated.length &&
    timingSafeEqual(received, calculated);
}

// rawBody is the body exactly as received, before JSON parsing.
// Read the signature from the X-Lanternaut-Signature header.
// Load secret from server-side secret storage.

Return any 2xx response within five seconds. Save or queue longer work and respond promptly. Use the event id to avoid processing the same event more than once; retries send the same body and ID.

Inspect retries and manage endpoints#

Recent deliveries shows the result, HTTP response code, attempts and next retry. A non-2xx response or timeout is retried after one minute, five minutes, 30 minutes and two hours, for up to five attempts.

Fix your receiver before using Resend on a failed delivery. Use Pause to stop new deliveries to an endpoint and Resume to enable it again. Delete removes the endpoint.

For event payload fields and API-based endpoint management, read the API reference.