Skip to content

Webhook

A webhook is an event-driven message automatically sent from one system to another when a defined event occurs.

A webhook is an event-driven message sent automatically from one system to another when something happens.

Instead of repeatedly asking whether something changed, the receiving system waits for the sending system to notify it.

GitHub describes webhooks as a way to subscribe to events and automatically receive data when those events occur. GitHub's webhook documentation

What It Means in Practice

An e-commerce system might send a webhook when:

  • An order is created
  • A payment succeeds
  • An order is cancelled
  • A refund occurs

For example:

Order created
     ↓
Webhook sent
     ↓
Accounting integration
     ↓
Invoice created

Webhook vs. API Request

Both use HTTP requests in many implementations.

The difference is who initiates the interaction.

### API request

Your integration asks:

Has anything changed?

### Webhook

The source system says:

Something changed. Here is the event.

Webhooks are therefore often used alongside APIs rather than instead of them.

Webhook vs. Polling

Polling repeatedly checks for changes.

A webhook reacts when the change happens.

GitHub explicitly recommends webhook events over frequent polling where appropriate because it reduces unnecessary API requests. GitHub REST API integration best practices

Why It Matters

Webhooks can make integrations:

  • Faster
  • More efficient
  • More event-driven
  • Less dependent on frequent scheduled checks

They are particularly useful for:

  • Payments
  • Orders
  • CMS publishing
  • Booking changes
  • Git deployments
  • Automation workflows

Reliability Considerations

Webhook delivery needs to be treated as a real system boundary.

A receiver should consider:

  • Authentication or signature validation
  • Duplicate deliveries
  • Failed deliveries
  • Retry behaviour
  • Event ordering
  • Idempotency
  • Logging

A webhook being sent does not necessarily mean the receiving system successfully processed it.

Common Problems

Common problems include:

  • Endpoint unavailable
  • Webhook secret not verified
  • The same event processed twice
  • Slow webhook processing
  • Event ordering assumptions
  • Failed deliveries never retried
  • Nobody monitoring failures
  • Integration logic tied to undocumented payload fields

How to Improve

Keep webhook handling predictable.

Validate the message, acknowledge it promptly, process it safely, log the result, and make repeated deliveries safe through Idempotency where appropriate.