Skip to main content
Helo can notify your application in real time whenever something happens to an email you’ve sent. 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:
EventDescription
acceptedHelo has accepted the message for delivery
processedThe message has been processed and handed off to the receiving server
deliveredThe receiving server confirmed delivery
openedThe recipient opened the email
clickedThe recipient clicked a tracked link
bouncedThe message could not be delivered
complainedThe recipient marked the message as spam
unsubscribedThe recipient unsubscribed
resubscribedA previously unsubscribed recipient opted back in
Do you need webhooks for an event we don’t yet support? Let us know!

​
How to set up webhooks

​
1. Create an endpoint in your app to receive requests

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 you can promptly respond. Then use a background service to read from the stream or queue and handle the actual processing work.
cURL
curl --location 'https://api.helohq.com/webhook-endpoints' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "url": "https://your-webhook-endpoint",
  "events": [
    "delivered",
    "opened"
  ],
  "channelId": "optional_channel_id",
  "additionalHeaders": [
    {
      "name": "X-Customer-Environment",
      "value": "production"
    }
  ],
  "enabled": true
}'

​
2. Set up your webhook in Helo

Navigate to the Webhooks section in your Helo account to create a new webhook. From here, you’ll need to specify:
  • 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.

​
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.
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.