TL;DR

  • A webhook is an HTTP callback: a provider POSTs an event payload (usually JSON) to a consumer URL so systems get real-time updates.
  • Use webhooks for low-latency notifications and APIs for on-demand or bulk reads; many integrations combine both (notify then GET full record).
  • Koodisi writes every attempt to a transaction log, emits metrics and traces as OpenTelemetry, and retries failed records through Engage.

A webhook is an HTTP callback: when an event happens in one system, that system sends an HTTP request to a configured URL so another system learns about the event immediately. This one-line definition answers what a webhook is and gives you a workable mental model to start building.

Webhooks are valuable because they provide push-based, real-time notifications that remove the need to poll. Example: when a customer places an order, your ecommerce platform posts an order-created webhook to your ERP so it can create an invoice.

Koodisi’s webhook trigger can host endpoints, support authentication, and provide delivery observability so teams can reduce the need to run custom public servers.

What is a webhook?

A webhook is an HTTP callback: the provider sends an HTTP POST (or sometimes PUT) to a consumer's URL when a specific event occurs. It is an event-driven HTTP request that carries a payload describing the event.

Core components:

  • Event source (provider): the system that detects an event, for example GitHub, Stripe, or Shopify.
  • Payload: structured data describing the event. JSON is most common, though XML and form-encoded bodies also appear.
  • Webhook endpoint: the consumer URL that receives the request.
  • Delivery mechanism: an HTTP request with headers such as content-type, delivery-id, and timestamp. Providers often include a signature header for verification.

Event-driven versus polling:

  • Polling asks the provider repeatedly whether something changed, which creates extra latency and load.
  • Webhooks push the change immediately, reducing requests and lowering latency for real-time workflows.

Common payload formats and headers:

  • JSON body with Content-Type: application/json.
  • Delivery ID or event ID header for deduplication, for example GitHub's delivery header.
  • Timestamp header so consumers can detect replay or stale events.
  • Signature header (HMAC) used to verify integrity, such as Stripe's signature scheme. These fields enable idempotency, tracing, and security.

Webhook vs API

When you choose between a webhook and a traditional API call, you are choosing between push and pull patterns.

Webhook API
Who starts it The provider, when an event happens The consumer, whenever it asks
Latency Near real time Depends on how often you poll
Request volume One request per event One request per check, even when nothing changed
Failed deliveries The provider retries The client retries its own request
Duplicates Expect them; deduplicate by event ID Controlled by the caller
Security Signature on each request (shared secret, HMAC) Token on each request (OAuth, API key)
Best for Notifications, triggers, status changes Lookups, bulk exports, historical queries

With polling the client asks the server again and again; with a webhook the server sends one event the moment it happens.

When to use which:

  • Use webhooks for real-time updates and notifications such as new orders, payment events, pushed logs, or CI build status.
  • Use APIs for one-off lookups, bulk exports, or querying historical data.

Hybrid pattern:

A common approach is webhook-notify plus API-fetch. Koodisi accepts inbound events and can call other systems via its REST Client, enabling no-code orchestration instead of custom glue code.

How webhooks work

  1. Provider detects an event, for example a payment succeeded.
  2. Provider constructs a payload, often signs it with a secret, and POSTs the payload to the configured webhook endpoint.
  3. The consumer validates the signature and content-type and returns an acknowledgement, usually a 2xx response.
  4. The provider logs the status and retries on failures according to its policy.

Delivery semantics:

  • Success is typically a synchronous 2xx HTTP response. The provider treats the delivery as complete and stops retrying.
  • Non-2xx responses or timeouts trigger retries. Providers use retry strategies such as exponential backoff with a maximum number of attempts.
  • Idempotency keys or a provider delivery ID let consumers deduplicate repeated deliveries.

Left-to-right pipeline: event triggers, payload created, POST sent, endpoint processes the request.

Retry strategies and duplicates:

  • Providers implement retry windows and backoff. Exact behavior varies by vendor; check each provider’s documentation for details.
  • Consumers must be idempotent and accept repeated deliveries without creating duplicate side effects.

Signing and verification:

  • Providers often sign payloads with HMAC using a shared secret and include a signature header. The consumer computes the HMAC over the payload and compares it to the header to verify integrity.
  • Timestamp headers help prevent replay attacks. Consumers should reject events older than an acceptable threshold.

Edge cases providers handle:

  • Slow consumer responses and timeouts. Providers set request timeouts and treat slow replies as failures.
  • Large payloads. Some providers send pointers and require the consumer to fetch the payload, or they use chunking and retries.
  • Network partitions. Providers may persist undelivered events and retry later. Some offer dead-lettering or replay tools for recovery.

Implementing webhooks: endpoints, security and scaling

Steps to implement a consumer endpoint:

  1. Create an HTTPS URL with a stable domain or use a hosted webhook trigger.
  2. Parse and validate the Content-Type header; JSON is widely used.
  3. Verify the signature using the shared secret and reject invalid signatures with 401/403.
  4. Respond quickly with a 2xx to acknowledge receipt and do minimal work inline.
  5. Enqueue the payload for asynchronous processing using a queue or background worker.

Developer sends events to an endpoint secured by HMAC/TLS and scaled via queues and retries.

Security best practices:

  • Require HTTPS to protect payloads in transit.
  • Rotate shared secrets regularly and avoid embedding them in code.
  • Validate signatures and timestamps to detect tampering and replay attacks.
  • Limit accepted IP ranges or use mutual TLS if available.
  • Apply rate limiting and authentication to prevent abuse.

Scaling and resiliency:

  • Use a durable queue such as SQS, Pub/Sub, or Kafka so handlers can acknowledge quickly and process work asynchronously.
  • Make handlers idempotent and use delivery IDs to record processed events.
  • Keep request handling short and scale horizontally with more instances behind a load balancer.
  • Throttle processing when downstream systems enforce rate limits.

Implementation notes for popular stacks:

  • Web frameworks: add a lightweight route that verifies a signature and pushes the payload to a queue. Keep the request handler under a second.
  • Serverless: avoid long-running synchronous work. Immediately enqueue a job and return 2xx.

Real-world examples

Slack incoming webhook

  • Use: post messages into a channel from external systems. The payload is JSON with text, attachments, and blocks per Slack’s docs. Slack incoming webhooks are a simple POST to a workspace URL.

GitHub push events

  • Use: trigger CI, mirror code, or notify chat when branches update. GitHub includes event-type headers and delivery IDs for tracing.

Stripe payment webhooks

  • Use: react to payment.succeeded or invoice.payment_failed. Stripe signs payloads and documents retry behavior; consumers should verify signatures using the secret.

Shopify webhooks and topics

  • Use: subscribe to topics such as orders/create or products/update so you only receive relevant events. Choose topics and validate payloads.

Forums and boards example

  • Flow: a forum emits a post-created webhook → a moderation workflow inspects content asynchronously → if flagged, the workflow notifies moderators.
  • Example flow: Koodisi webhook trigger receives a Shopify order-created event, validates the schema against a registry, maps fields into an accounting format, and calls an external accounting system via Koodisi's REST client. No custom public server is required. Retries and failure recovery are visible in the platform’s transaction logs and recovery surfaces.

Quick one-line use cases:

  • Real-time analytics, notifications and alerts, SaaS-to-SaaS sync, CI/CD pipelines, and audit logging.

Monitoring and reliability

Important webhook health metrics to track:

  • Success rate: percentage of deliveries that return 2xx. Aim for a high success rate on critical endpoints.
  • Delivery latency: time from provider sending to consumer 2xx response.
  • Retry counts: average attempts per delivery; high averages indicate instability.
  • Failure rates: percentage of 4xx and 5xx responses and timeouts.

Logs and dashboards to keep:

  • Delivery timestamps, response codes, payload sizes, and unique delivery IDs for tracing.
  • Correlate webhook deliveries with downstream processing traces.

Operational features to consider:

  • Replay or resend events for recovery.
  • Dead-letter queues for persistent failures.
  • Throttling controls and configurable retry policies.
  • Schema versioning and validation so consumers fail fast on contract changes.

Tooling:

  • Provider dashboards such as Stripe and GitHub show delivery attempts and recent responses; use them for triage.
  • Testing tools: ngrok for local development and requestbin-like services to capture webhooks.
  • iPaaS observability: Koodisi emits metrics and traces for each run, writes every attempt to a transaction log, and handles failed records in Engage.

Best practices and common pitfalls

Best practices:

  • Always use HTTPS and verify signatures.
  • Respond quickly with a 2xx and offload heavy work to queues.
  • Make handlers idempotent and use delivery IDs.
  • Document webhook schemas and error codes. Version payload contracts and validate incoming events.
  • Monitor delivery statistics and set alerts for sustained failure rates.

Common mistakes:

  • Doing synchronous processing that times out providers.
  • Ignoring duplicate deliveries and creating duplicate side effects.
  • Storing secrets in plaintext or code repositories.
  • Skipping monitoring and not offering replay options for historic events.

Governance advice:

  • Test webhooks in staging and provide a documented retry policy in your API docs.
  • Offer a way to resend historic events and set reasonable retention for stored events.

If you want fewer ops responsibilities, choose an iPaaS or a hosted webhook trigger. Koodisi reduces the need to run public endpoints, adds schema governance, and surfaces delivery and recovery tooling so teams can focus on business logic.

Frequently asked questions

What is a webhook and how is it different from an API?

A webhook is a push-based HTTP callback where the provider POSTs an event payload to a consumer URL when something changes. An API is usually pull-based: the consumer requests data from the provider. Use webhooks for real-time notifications and APIs for on-demand or bulk reads.

How do I secure a webhook endpoint ?

Require HTTPS, validate HMAC signatures using a shared secret, check timestamp headers to prevent replay attacks, rotate secrets periodically, and consider IP allowlisting or mutual TLS where available.

What should I do when a webhook payload fails or is delivered twice?

Acknowledge receipt quickly and enqueue work. Use delivery IDs or idempotency keys to deduplicate. For persistent failures, surface the event to a dead-letter queue or recovery dashboard so someone can fix and replay it.

How can I monitor webhook delivery health and get delivery statistics?

Track success rate (percent of 2xx), delivery latency, retry counts, and per-endpoint error distributions. Koodisi emits metrics and traces for every workflow run and keeps a transaction log of each attempt.

Does Shopify require webhook topics and how do I handle schema changes?

Shopify requires you to subscribe to specific topics so only relevant events are sent. Keep a schema registry or contract, version payloads, and validate incoming events to detect breaking changes early.

Can I use webhooks without running my own server ?

iPaaS platforms like Koodisi offer hosted webhook triggers that host endpoints, handle auth, and provide observability so you do not manage public servers.

Useful links:

  • Explore Koodisi connectors in the connector catalog: Connectors.
  • Learn how triggers and orchestration fit into workflows: Workflow orchestration.
  • See observability and metrics Koodisi captures: Observability.
  • Understand recovery and retry tooling: Engage.

Ready to try a hosted webhook trigger and skip running your own public endpoint? Request a demo: /request-demo