Webhooks
Real-time notifications for your system: endpoints, events and deliveries.
What it's for
A webhook notifies your system, through a signed HTTPS request, whenever something happens in Postal: an email delivered, a bounce, a complaint, an email received, a new contact. It is the way to react in real time instead of polling the API.
When to use: To update your database with the result of sends, deactivate addresses that bounced, open a ticket when an email arrives and alert the team when sending is paused.
#Webhooks list
Where to find it: Developers › Webhooks. Address: app.postal.so/webhooks.
| Field | What it does |
|---|---|
| Add webhook | Opens the setup form: the Endpoint URL and the Events. |
| Endpoint URL | Must be HTTPS and respond with 2xx within 15 seconds. Postal sends a signed POST for each event you choose. |
| Events | Check the ones you want to receive (see Events). Select all / Deselect all apply to everything, and there is a matching pair in each group. The counter reads N of M selected. |
| Column | What it shows |
|---|---|
| Endpoint | The URL (a link to the details). |
| Events | How many events the webhook subscribes to. |
| Status | Active; Paused (by someone on the team); or Disabled after failures (Postal disabled it after 5 days in a row without a single successful delivery). |
| Created | The creation date. |
See also: Webhooks (guide) · Webhooks (API).
#Events and webhook details
Events you can subscribe to
| Group | Events |
|---|---|
| E-mails | email.sent (Sent), email.delivered (Delivered), email.delivery_delayed (Delivery delayed), email.bounced (Bounced), email.complained (Marked as spam), email.opened (Opened), email.clicked (Link clicked), email.replied (Replied), email.failed (Failed), email.scheduled (Scheduled), email.suppressed (Suppressed) and email.received (Received, in inboxes). |
| Domains | domain.created, domain.updated and domain.deleted. |
| Suppressions | suppression.added (Added) and suppression.removed (Removed). |
| Contacts | contact.created, contact.updated, contact.deleted, contact.segment_entered (Entered a dynamic segment) and contact.segment_exited (Left a dynamic segment). |
| Forms | form.submitted (Signup received). |
| Campaigns | broadcast.sent (Sending finished). |
| Inbox | inbox.thread.created, inbox.thread.updated, inbox.thread.deleted and inbox.draft.created (AI draft created). |
| Sending | sending.paused (Sending paused) and sending.resumed (Sending resumed), to alert the team right away. |
The body format of each event is in Webhooks › Payload.
Webhook details
Clicking a webhook opens its page. In the header:
| Button | What it does |
|---|---|
| Send test event | Fires a webhook.test event to the endpoint (Test event sent). It shows up in the deliveries with the Test badge. |
| Reactivate | Only on a webhook that is Disabled after failures: it starts sending again. First, check that the endpoint is online and responds with 2xx. |
| Pause / Enable | Stops and resumes sending without deleting anything. |
| Edit | Changes the URL and the events. |
| Remove webhook | The trash can icon. The endpoint stops receiving events and the delivery history is deleted. |
| Section | What it is |
|---|---|
| Notices | On an active webhook whose deliveries are failing, Deliveries have been failing since ...: if none succeeds within 5 days, the endpoint is disabled and the team's owners and admins get an email. Once disabled, We disabled this endpoint on .... |
| Signing secret | The whsec_... secret used to verify the webhook-signature (or svix-signature) headers of the requests. The Show secret/Hide secret and Copy secret buttons. Generate new replaces the secret: the current one stops working immediately, so update your system right after. |
| Subscribed events | The list of events this endpoint receives. |
| Ignore contact changes coming from | Loop protection: contact events whose change came from a listed source (for example, the very system that receives this webhook and also writes to Postal) are not sent. |
| Deliveries | The history of events sent, for 30 days. |
Deliveries
| Column | What it shows |
|---|---|
| Event | The event type. |
| Status | Pending, Retrying (with next ... showing when), Delivered or Failed. |
| Attempts | How many times Postal tried. |
| Created | When the event was generated. |
| Resend | Fires that event again. |
Clicking a delivery opens its attempts: the HTTP code your endpoint returned (or No response), the time, the duration in milliseconds and the response body or the error. Responses outside 2xx are retried automatically for about 27 hours (8 attempts), always with the same webhook-id, so your system can handle repeats.
Tip
Check the signature of every request and respond with 2xx quickly: do the heavy work later, in a queue. See the step-by-step in Signature.
See also: Events (guide) · Signature · Attempts · Resend (API).