Webhook

Definition

A webhook is a user-defined HTTP callback — when an event occurs, the source system sends an HTTP POST request to a configured URL. It is a way for one application to push real-time data to another application, eliminating the need for polling.

Webhooks are sometimes called “reverse APIs” because they push data to the consumer rather than waiting for the consumer to request it.

Webhook vs Polling

Aspect Webhook Polling
Direction Push (source → consumer) Pull (consumer → source)
Real-time Near-instant Depends on poll interval
Bandwidth Only when events occur Constant, even with no data
Complexity Consumer must expose endpoint Simple (no server setup needed)
Reliability Depends on endpoint availability Guaranteed delivery (if retries)
Use case Notifications, CI/CD triggers Status checks, sync

Webhook Workflow

Event occurs (e.g., GitHub push)
    │
    ▼
Source System (GitHub/GitLab)
    │
    │ HTTP POST
    │ Content-Type: application/json
    │ Body: { "event": "push", "repo": "...", "ref": "..." }
    ▼
Consumer Endpoint (your server)
    │
    │ HTTP 200 OK (acknowledge receipt)
    ▼
Process event (e.g., trigger CI/CD build)

Webhook Payload Example (GitHub)

{
  "action": "push",
  "repository": {
    "name": "my-app",
    "owner": { "login": "my-org" }
  },
  "pusher": { "name": "developer", "email": "dev@example.com" },
  "ref": "refs/heads/main",
  "commits": [
    { "sha": "abc123", "message": "fix: resolve login bug" }
  ]
}

Webhook Use Cases

Use Case Source Consumer
CI/CD trigger GitHub/GitLab Jenkins, GitHub Actions
Chat notifications GitHub, Jira, CI Slack, Discord, Teams
Payment processing Stripe, PayPal E-commerce backend
Monitoring alerts Prometheus, Datadog PagerDuty, Slack
CRM updates Salesforce, HubSpot Internal systems
File upload S3, Dropbox Processing pipeline
Auth events Auth0, Okta User session management

Webhook Reliability

Issue Solution
Endpoint down Retry with exponential backoff
Slow response Acknowledge quickly, process async
Duplicates Idempotent handlers (check event ID)
Security Verify signature (HMAC), use tokens
Debugging Log payloads, use webhook testing tools

Webhook Security

# GitHub webhook secret verification
# Source sends: X-Hub-Signature-256: sha256=...
# Consumer verifies:
import hmac, hashlib
expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
if hmac.compare_digest(expected, received):
    process(payload)
Method Description
Secret token Shared secret in header (X-Webhook-Secret)
HMAC signature Cryptographic signature of payload
TLS HTTPS for transport security
IP whitelist Restrict source IP addresses
OAuth Token-based authentication

Webhook Testing Tools

Tool Purpose
ngrok Expose local endpoint for testing
Webhook.site Temporary webhook endpoint for debugging
RequestBin Capture and inspect webhook payloads
Pipedream Visual webhook workflow builder
GitHub webhooks test Built-in test in repo settings

Webhook Limitations

  • Endpoint must be publicly accessible (or use tunneling for local dev)
  • No guaranteed delivery without retry logic
  • No built-in ordering (unless source provides it)
  • Firewall/nat issues for on-prem consumers
  • Rate limiting may apply from source
  • Api — webhooks trigger CI/CD pipelines
  • Slack — popular webhook consumer for notifications
  • Kubernetes — webhooks implement event-driven architecture
  • REST — webhooks use HTTP/REST for delivery

References