Webhooks

Overview

Mercat webhooks deliver real-time HTTP POST notifications about changes to stores, orders, and menus, eliminating the need to poll the API.

Configuration

Provide your endpoint URL and (optionally) a webhook secret during API setup

Ensure your endpoint is publicly accessible via HTTPS

The Mercat team will enable webhook delivery for your account

Event Types

stores.update stores.update

orders.create orders.create

orders.update orders.update

menus.update menus.update

Event Structure

{
  "client_id": "your-client-id",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "orders.update",
  "event_timestamp": 1705348800,
  "api_version": "v1",
  "event_data": { }
}

Field	Type	Description
`client_id`	string	Your client identifier
`event_id`	string (UUID)	Unique event identifier. Use for idempotency
`event_type`	string	One of: `stores.update`, `orders.create`, `orders.update`, `menus.update`
`event_timestamp`	integer	Unix timestamp when the event occurred
`api_version`	string	API version (currently `v1`)
`event_data`	object	Full resource object (Store, Order, or Menu)

HTTP Request

Method: POST

Headers:

Header	Description
`Content-Type`	`application/json`
`X-Request-Id`	Unique UUID per request (useful for debugging)
`X-Webhook-Secret`	Your configured secret (if set)

Timeout: 10 seconds. Your endpoint must respond within this time.

Endpoint Requirements

Accept POST requests with JSON body

Respond with HTTP 200 within 10 seconds

Validate X-Webhook-Secret if configured

Handle duplicate event_id idempotently

Process heavy logic asynchronously (respond first, process after)

Security

The X-Webhook-Secret header is the primary authentication mechanism.

Delivery Guarantees

Retries: Failed deliveries (non-200 or timeout) are retried automatically with exponential backoff

Deduplication: Content-based deduplication prevents identical events from being sent twice. Use event_id for application-level idempotency

Ordering: Events are generally delivered in order per resource, but retries or network issues may cause occasional out-of-order delivery. Use event_timestamp to detect outdated events

Best Practices

Respond quickly -- return 200 OK before doing heavy processing

Verify secret -- validate X-Webhook-Secret on every request

Be idempotent -- deduplicate using event_id

Overview#

Configuration#

Event Types#

Event Structure#

HTTP Request#

Endpoint Requirements#

Security#

Delivery Guarantees#

Best Practices#