Webhooks Overview

Webhooks let your app receive real-time HTTP POST notifications when events happen in a merchant's store. Instead of polling the API for changes, the platform pushes events to your endpoint as they occur.

How Webhook Delivery Works

When something happens on the platform (an order is placed, a product is updated, a charge is approved), the following sequence executes:

1. Platform event occurs (e.g., order status changes)
         |
2. publishPlatformEvent() sends event to Inngest queue
         |
3. deliverWebhooks (fan-out) finds all active subscriptions
   matching the event topic + store_id
         |
4. For each subscription, a separate deliverSingleWebhook
   event is published
         |
5. Each delivery: HMAC-signed POST to the subscription's target_url
         |
6. Independent retry policy per delivery (up to 5 retries, 6 total attempts)

Step by Step

Event occurs -- A router handler (e.g., order status update) calls publishPlatformEvent('order.status_changed', store_id, payload). This is fire-and-forget from the platform's perspective; the API response is not blocked.
Queue ingestion -- The event is published to the Inngest queue as app/order.status_changed. This ensures reliable processing even under load.
Fan-out -- The deliverWebhooks function triggers on any app/* event. It queries the database for all active webhook subscriptions that match the store_id and event_topic.
Individual delivery events -- For each matching subscription, a separate app/webhook.deliver event is published. This means each subscription gets its own independent delivery pipeline.
Delivery -- The deliverSingleWebhook function POSTs the payload to the subscription's target_url with HMAC-SHA256 signature headers. Each delivery has a 15-second timeout.
Retries -- If delivery fails (non-2xx, timeout, or connection error), the system retries up to 5 times (6 total attempts) with an escalating backoff schedule: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours.

Key Concepts

Fire-and-Forget Publishing

When the platform publishes an event, it does not wait for webhook delivery to complete. The API response returns immediately. If the Inngest queue is temporarily unavailable, the event is logged but the API call still succeeds.

Independent Delivery Per Subscription

If three apps subscribe to order.status_changed on the same store, each gets its own delivery pipeline with independent retries. App A failing does not affect delivery to App B or App C.

Automatic Subscription on Install

When a merchant installs your app, the platform checks your app's webhook_topics configuration. For each declared topic, it automatically creates a webhook subscription pointing to your app's webhook_receive_url. You don't need to call the Webhooks API during the install flow unless you need custom target URLs.

Manual Subscription Management

You can also create, list, and delete subscriptions programmatically using the Webhooks API. This is useful when you need to subscribe to additional topics after installation or change your target URL.

Payload Enrichment

Order event payloads are automatically enriched before delivery. Even if the original event only contained order_id and status, the delivery pipeline adds:

customer_name -- From the order's shipping address or customer record
customer_phone -- From the order's shipping address or customer record
tracking_id -- Courier tracking code, if assigned
store_name -- The merchant's store name
order_number -- The store-specific serial order number

This means your webhook handler always receives a complete payload regardless of how the event was originally published.

Signing Secrets

Each webhook subscription has a unique signing secret (prefixed with whsec_). The secret is generated when the subscription is created and returned only once in the creation response. All deliveries to that subscription are signed with this secret using HMAC-SHA256.

What's Next

Event Topics -- Complete list of available events and payload shapes
Receiving Webhooks -- How to verify signatures and process deliveries
Retry Policy -- Retry schedule, failure handling, and auto-disable behavior
Webhooks API -- Create, delete, and rotate secrets for subscriptions programmatically