All articles › Webhooks & Integrations

Webhook Event IDs, Replay and Transactional Events

Deduplicate deliveries with event IDs, replay a past delivery, and receive events for transactional email.

Webhooks send a signed JSON request to your server whenever something happens in your account. Open Webhooks from the user menu to create endpoints and choose the events they receive. Webhooks are available on the Growth plan and above.

Payload and event IDs

Every delivery has the same shape: id, event, timestamp, organization_id and data. The id starts with evt_ and is also sent in the X-Webhook-Id header.

  • The id is unique per event, and stays the same when Mailnaptic retries a failed delivery or when you replay it, so you can use it to ignore duplicates.
  • The id appears in the delivery log of each endpoint.
  • Deliveries made before event ids were introduced have no id.

Verifying signatures

Each request is signed with the secret of the endpoint. X-Webhook-Signature-V2 signs the timestamp, a dot and the raw body, and X-Webhook-Timestamp carries the timestamp. Verify V2 and reject old timestamps. The older X-Webhook-Signature header, which signs the body only, is still sent. Webhook actions inside automations that have a signing secret use the same V2 headers, so one verification routine works for both.

Retries

A delivery succeeds on any 2xx response. Failed deliveries are retried up to 4 more times, after 30 seconds, 5 minutes, 30 minutes and 2 hours.

Replaying a delivery

If your server was down or had a bug, you can send a past delivery again.

  1. Open Webhooks and click Deliveries on the endpoint.
  2. Click Replay on the delivery and confirm.
  3. A message shows whether your server accepted it.

The replay sends the same payload with the same event id, a fresh signature and timestamp, and the header X-Webhook-Replay: true. It is a single attempt and is not retried automatically. It appears in the delivery log as a new row marked Replay. Make sure your receiver handles duplicates before you replay.

  • Only owners and admins can replay, and replays are limited to 10 per minute.
  • The button is disabled when the delivery cannot be replayed, for example when it was sent before event ids existed or when its payload was too large to be stored in full.
  • A disabled endpoint cannot receive replays. Enable it first.

Transactional email events

Emails sent with the transactional API now return a message_id that starts with txm_. These webhook events are also sent for transactional emails:

  • email.delivered when the message was accepted by the mail relay.
  • email.bounced and email.complained when a bounce or complaint is reported for it.

Their data has type set to transactional and the message_id. Transactional emails do not produce open or click events. A bounce or complaint only carries the message_id when the report includes the original message headers.

Opens

email.opened includes data.open_source, so you can tell human opens from automatic ones. See Apple Mail Privacy Protection and open rates.

Tip:

The full list of events, headers and examples is in the

API documentation

under Webhook endpoints.

Was this helpful?

Copy for AI (Markdown)

Related articles

Mailnaptic · Help center