Skip to content
MailSlurp logo

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.

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

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:

{
  "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, 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:

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 shows the acceptance order.

To test what happens after an email arrives, create an inbox, 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.