Webhooks
A webhook posts an event to your URL the moment it happens in Ballast, so your CRM, Slack or Zapier hears about a reply without polling. This page covers setting them up; the payload and the signature check are in the API reference.
Ballast is cold email software with every feature on every plan. Connect unlimited mailboxes, send sequences at a pace your domains survive, and handle replies in one inbox, priced by the emails you send.
Last updated
Events
| Event | When |
|---|---|
lead.replied | A lead answered a campaign email (out-of-office and auto-replies excluded). |
lead.labeled | A reply got a label, from AI, a rule, a person or the API. |
lead.bounced | An email to a lead bounced hard. |
lead.unsubscribed | A lead unsubscribed, by link, one-click header or reply. |
lead.won | A lead was marked won. |
campaign.paused | A campaign stopped sending: paused by someone, a label, a breaker or its end date. |
Adding an endpoint
- Open Settings, Webhooks, add your URL and pick the events it should get. Owners and admins manage webhooks.
- The URL must be https and reachable on the public internet. Addresses on private networks are refused, when you add the URL and again on every delivery.
- Ballast shows the signing secret once when you create the endpoint. Admins can show it again or replace it later.
- Press Send test event to post a sample event to it.
Delivery and retries
- A 2xx answer within 10 seconds counts as delivered. Anything else, redirects included, is retried.
- Up to 8 retries, waiting longer each time from 30 seconds, about two hours in all.
- After 15 deliveries in a row fail every retry, Ballast turns the endpoint off. Turn it back on when your server is fixed; that clears the failure count.
- The delivery log shows each delivery with the payload as sent, and Send again on failed ones. Deliveries are kept for 30 days.
- Events can arrive more than once or out of order. Use the event id to skip ones you have seen.
Payload and signature
Every request carries a Ballast-Signature header, an HMAC-SHA256 of the timestamp and the body with your secret. Check it before you trust the payload. The payload shape, an example and a Node snippet that verifies the signature are in the API reference, Webhooks.