Webhooks

Helo can notify your application in real time whenever something happens in your account — such as an email being delivered, or a domain’s DNS records being verified. These notifications arrive as HTTP POST requests to a URL of your choosing — that’s a webhook. For example, instead of polling the API to find out whether an email was delivered or opened, we’ll send you a webhook when such an event happens, and your app just listens and reacts.

Supported webhook events

Helo can send you webhooks whenever any of the following events occur.

Message events

Message events track the emails you send, from acceptance through delivery and engagement.

Event	Description
`message-accepted`	Helo has accepted the message for delivery
`message-processed`	The message has been processed and is ready for delivery
`email-delivered`	The receiving server confirmed delivery
`email-bounced`	The message could not be delivered
`email-opened`	The recipient opened the email (requires open tracking)
`link-clicked`	The recipient clicked a tracked link (requires click tracking)
`recipient-complained`	The recipient marked the message as spam
`recipient-unsubscribed`	The recipient unsubscribed
`recipient-resubscribed`	A previously unsubscribed recipient opted back in

Domain events

Domain events track changes to the DNS records of your sending domains. Use them to react when a domain becomes ready for sending, or when a record stops resolving correctly.

Event	Description
`domain-key-verified`	The domain’s DKIM key DNS record was verified
`domain-key-verification-failed`	Verification of the domain’s DKIM key DNS record failed
`return-path-domain-verified`	The domain’s Return-Path DNS record was verified
`return-path-domain-verification-failed`	Verification of the domain’s Return-Path DNS record failed

Domain events aren’t tied to a single Channel. They’re sent to webhooks for all channels, and to webhooks for any channel the domain is available on. Do you need webhooks for an event we don’t yet support? Let us know!

Webhook payloads

Every webhook is a JSON object. The eventType field identifies the event, and timestamp says when it occurred.

Message event payloads

Message events include details about the message, so you can match the event to your own records:

{
  "eventType": "email-delivered",
  "timestamp": "2026-10-26T12:00:00Z",
  "messageId": "01930f2a-4b3c-7d8e-9f0a-1b2c3d4e5f6a",
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "mailType": "transactional",
  "recipient": "jane@example.com",
  "subject": "Your order has shipped",
  "tags": ["order"],
  "metadata": { "orderId": "1234" },
  "details": {
    "response": "250 2.0.0 OK"
  }
}

message-accepted and message-processed include a recipients array, covering every recipient of the message.
All other message events include a single recipient.
Most events include a details object with event-specific information — such as the bounce type for email-bounced, or the clicked link for link-clicked. Fields are omitted when the information isn’t available.

Domain event payloads

Domain events identify the domain and the DNS record that changed:

{
  "eventType": "domain-key-verified",
  "timestamp": "2026-10-26T12:00:00Z",
  "domainId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "domainName": "example.com",
  "dnsRecordHost": "20261026120000-helo._domainkey"
}

How to set up webhooks

First, set up a publicly accessible URL that Helo can communicate with. Your endpoint needs to accept HTTP POST requests and respond with a 200 OK to let Helo know the event was received successfully. We recommend designing your webhook endpoint so most of the work is done asynchronously. When you receive the webhook, write a message to a queue or event stream, so your API can promptly respond. Then use a background service to read from the stream or queue and handle the actual processing work. When you create the webhook in Helo, you’ll need to specify the following:

URL (required): This is the endpoint we’ll send requests to.
Events (required): Select the types of events you’d like us to send webhooks for.
Channel (optional): You can receive webhooks for a specific channel. If omitted, you’ll receive webhooks for all channels.
Additional headers (optional): If you’d like Helo to include additional custom headers when sending webhooks, you can define them here. Header names must start with X-Customer- (for example, X-Customer-Id), and you can add up to 10.

You can also create, edit, or delete your webhooks via the Webhooks API endpoint.

Request headers

Every webhook request includes the following headers:

Header	Description
`X-Helo-Webhook-Id`	The ID of the webhook the request was sent for.
`X-Helo-Webhook-Event-Id`	A unique ID for the event. Retries of the same event use the same ID, so you can use it to ignore duplicates.
`X-Helo-Webhook-Signature`	The signature you can use to verify the request.
`X-Helo-Channel-Id`	The Channel the event relates to. Only included for events tied to a single Channel.
`X-Helo-Webhook-Test`	Set to `true` for test webhooks. Not included for real events.

Verify webhook signatures

Helo signs every webhook request, so you can confirm it came from Helo and wasn’t modified in transit. We strongly recommend verifying the signature before acting on a webhook. Each webhook has its own signing key, returned as payloadSigningKey when you create or retrieve the webhook. If your key is ever exposed, regenerate it.

Verify with an SDK

The Helo SDKs include a helper that verifies the signature for you. For example, in Node.js:

import { verifyWebhookSignature, WebhookSignatureError } from "@helo-email/sdk";

app.post("/webhooks/helo", express.raw({ type: "application/json" }), (req, res) => {
  try {
    verifyWebhookSignature(
      req.header("X-Helo-Webhook-Signature"),
      req.body, // the raw body, exactly as received
      process.env.HELO_WEBHOOK_SIGNING_KEY,
    );
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      return res.status(400).send("Invalid signature");
    }
    throw error;
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // ... queue the event for processing
  res.sendStatus(200);
});

The helper also rejects requests whose timestamp is more than 5 minutes from the current time, to protect against replayed requests.

Always verify against the raw request body. Parsing and re-serializing the JSON changes the bytes, and the signature won’t match.

Verify manually

The X-Helo-Webhook-Signature header has the form:

t=1793016000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

t is the Unix timestamp (in seconds) when the request was signed.
v1 is the signature: a hex-encoded HMAC-SHA256 of the string {t}.{raw request body}, using your webhook’s signing key.

To verify a request:

Parse the header

Split the header on ,, then split each element on the first =. Ignore any elements you don’t recognize — new signature versions may be added in future.

Compute the expected signature

Join the timestamp, a ., and the raw request body. Compute the HMAC-SHA256 of that string with your signing key, and hex-encode it in lowercase.

Compare the signatures

Compare your signature to the v1 value with a constant-time comparison. Reject the request if they don’t match.

Check the timestamp

Reject the request if the timestamp is too far from the current time (we recommend 5 minutes).

Retry schedule

If Helo doesn’t receive a 200 response, we’ll retry the delivery automatically for up to 24 hours. We use an exponential backoff with an initial retry interval of 10 seconds, e.g.,

1st attempt
10 seconds later… 2nd attempt
20 seconds later… 3rd attempt
40 seconds later… 4th attempt
etc.

Because a webhook can be retried after your endpoint has already processed it (for example, if your response timed out), you may occasionally receive the same event more than once. Use the X-Helo-Webhook-Event-Id header to detect duplicates.

First attempts are placed in a separate queue from retry attempts within our webhook processing system and have a timeout of 5 seconds. Making sure you respond quickly on the first attempt will ensure timely delivery of your webhooks. Retry attempts have a timeout of 60 seconds.

Getting started

Core concepts

Platforms

Account management

Supported webhook events

Message events

Domain events

Webhook payloads

Message event payloads

Domain event payloads

How to set up webhooks

Request headers

Verify webhook signatures

Verify with an SDK

Verify manually

Retry schedule

​Supported webhook events

​Message events

​Domain events

​Webhook payloads

​Message event payloads

​Domain event payloads

​How to set up webhooks

​Request headers

​Verify webhook signatures

​Verify with an SDK

​Verify manually

​Retry schedule

Supported webhook events

Message events

Domain events

Webhook payloads

Message event payloads

Domain event payloads

How to set up webhooks

Request headers

Verify webhook signatures

Verify with an SDK

Verify manually

Retry schedule