# What Is a Webhook? Meaning, Examples, and Reliable Event Callbacks

A webhook is an HTTP callback that pushes event data to your application. Learn webhook meaning, examples, payloads, URLs, retries, security, and testing patterns for reliable integrations.

A webhook is an HTTP callback: one system sends your endpoint an event payload when something happens.

Instead of repeatedly asking an API "anything new?", your app receives pushed events as they occur.

## Webhook meaning in one sentence

A webhook means "call this URL when this event happens."

The provider owns the event. Your application owns the webhook URL, validates the request, stores the event, and then starts any follow-up work.

Common webhook events include:

- `email.received`
- `email.delivered`
- `email.bounced`
- `invoice.paid`
- `user.created`
- `build.failed`

## Why teams use webhooks

Webhooks are useful when you need near-real-time reactions without heavy polling.

Common examples:

- payment succeeded/failed,
- user signed up or changed plan,
- email delivered/bounced/complained,
- document processed and ready,
- CI/CD pipeline status changes.

## Webhook vs polling API

| Approach | How it works                             | Typical tradeoff                               |
| -------- | ---------------------------------------- | ---------------------------------------------- |
| Polling  | Your app requests updates repeatedly     | Simpler control flow, higher API/load cost     |
| Webhook  | Provider pushes updates to your endpoint | Lower latency, requires robust receiver design |

For event-driven systems, webhooks usually reduce latency and infrastructure overhead.

## How webhooks work (end-to-end)

1. You register a callback URL with a provider.
2. A business event occurs in the provider system.
3. Provider sends an HTTP request (often `POST`) to your callback URL.
4. Your endpoint validates, records, and processes the payload.
5. Your endpoint returns success/failure status so the provider can decide retry behavior.

Reliable consumers save a durable pending job before acknowledging the event, then process that job asynchronously.

## Webhook URL, endpoint, and payload

These terms are often used together, but they are not the same thing.

| Term             | Meaning                                                  | Example                                        |
| ---------------- | -------------------------------------------------------- | ---------------------------------------------- |
| Webhook URL      | The public HTTPS address the provider calls              | `https://api.example.com/webhooks/email`       |
| Webhook endpoint | The server route that receives and validates the request | `POST /webhooks/email`                         |
| Webhook payload  | The JSON or form data sent with the event                | Event ID, type, timestamp, and resource fields |
| Webhook secret   | Shared signing material used to verify the sender        | HMAC signing secret                            |

This illustrative payload shows a generic event shape, not the MailSlurp API schema:

```json
{
  "id": "evt_01JZ9WZ3",
  "type": "email.received",
  "createdAt": "2026-06-15T10:30:00Z",
  "data": {
    "inboxId": "inbox_123",
    "messageId": "email_456",
    "from": "customer@example.com"
  }
}
```

Do not build business logic around field names until you have checked the provider's schema, versioning rules, and signature model.

## Webhook payloads and delivery semantics

Most providers do **at-least-once delivery**, which means duplicates can occur.

Design implications:

- make handlers idempotent,
- use event IDs for deduplication,
- tolerate out-of-order delivery,
- store raw payloads for replay and audit.

## Status codes and retry behavior

A `2xx` response usually acknowledges delivery. Timeouts and error responses indicate failure, but automatic retry rules vary by provider. For example, [GitHub documents redelivery of missed webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks#redeliver-missed-deliveries), while MailSlurp queues unsuccessful deliveries for retry. The receiver pattern is:

1. verify the request using the provider's authentication scheme
2. durably store the pending work, or confirm the same job already exists
3. return `2xx` quickly
4. process slow downstream work in a queue

Avoid doing long API calls, template rendering, or customer-visible updates directly inside the webhook request path.

## Security checklist for webhooks

1. Verify provider signatures (HMAC/JWT or equivalent).
2. Expose an HTTPS callback URL and keep certificate verification enabled.
3. Deduplicate event IDs. If the provider includes a signed timestamp, enforce its documented replay window.
4. Restrict inbound source ranges if provider supports it.
5. Never trust payload fields without schema validation.

"Secret URL only" is not enough for production security.

## Reliability checklist

1. Authenticate and validate the event, then durably save its pending work.
2. Return 2xx after that save succeeds; let a worker perform the slow task.
3. Implement dead-letter and replay path.
4. Track error rate, retry depth, and processing lag.
5. Keep a manual reprocess tool for incident response.

## Webhooks for email workflows

Email systems use webhooks for delivery observability and automation:

- delivered,
- bounced,
- complaint,
- opened/clicked (where supported),
- inbound message received.

That enables stateful workflows like suppression lists, escalations, and customer-visible status updates.

Related guides:

- [Email webhooks](/guides/email-webhooks/)
- [Email webhooks product page](/product/email-webhooks/)
- [Testing webhooks](/guides/testing-webhooks/)
- [Inbound email routing](/solutions/inbound-email-routing/)
- [What is transactional email?](/blog/what-is-transaction-email/)

## Testing webhook integrations safely

A robust test setup should validate:

- URL routing and request method
- signature verification logic,
- duplicate event handling,
- timeout/retry behavior,
- schema evolution compatibility.

For email events, MailSlurp can generate realistic message and delivery events so teams can test webhook consumers before production release.

For MailSlurp inbound events, deduplicate the notification using `messageId` and retrieve the email using `emailId`. Those fields have different jobs; the [email-to-webhook receiver example](/guides/email-webhooks/#receive-the-email-webhook-in-node) shows the acceptance order.

To test what happens after an email arrives, [create an inbox](/guides/creating-inboxes/), trigger a message, receive the webhook and fetch the email. Then check that your application completed the expected work, such as creating a support ticket.

## Anti-patterns to avoid

- synchronous downstream API calls inside webhook request path,
- no deduplication key strategy,
- treating missing events as impossible,
- no replay tooling during incidents.

## Final take

Webhooks are a powerful event integration pattern, but only when handlers are built for security, retries, and idempotency. Treat the webhook consumer like production infrastructure, not a thin demo endpoint.
