Webhooks

Webhooks let you receive real-time notifications when events happen in your customers' connected stores. Instead of polling the API, EcartAPI delivers a POST request to your URL whenever a relevant event occurs — a new order, an inventory update, a product change, and more.

Supported events

The events available depend on the platform the connected store uses. To see which resource/action combinations are available for a given platform, send an OPTIONS request to the webhooks endpoint with a valid store token:

OPTIONS /api/v2/webhooks
Authorization: Bearer {access_token}

The response lists every supported resource and action for that store's platform. Always use OPTIONS to discover supported events before registering webhooks — the list varies significantly between platforms.

Creating a webhook

POST /api/v2/webhooks
Authorization: Bearer {access_token}

{
  "resource": "orders",
  "action": "create",
  "url": "https://yourdomain.com/webhooks/orders",
  "auth": "secret-value-for-your-server"
}

Field	Required	Description
`resource`	Yes	The data type to subscribe to (e.g. `orders`, `products`, `inventory`).
`action`	Yes	The event to subscribe to (e.g. `create`, `update`, `delete`).
`url`	Yes	Your endpoint URL. EcartAPI will POST to this address on each event.
`auth`	No	A value EcartAPI will send as the `Authorization` header in every delivery. Useful for authenticating requests on your side. This value cannot be retrieved after creation — store it securely when you create the webhook.

CRUD operations on webhook records (create, update, delete, list) count toward your monthly request quota. Webhook deliveries themselves are free.

Payload structure

EcartAPI delivers the resource object directly as the request body — there is no envelope wrapper. The payload is identical to what you would receive from the corresponding REST endpoint for that resource.

For example, an orders / create delivery sends the full order object:

{
  "id": "111-2223334-4445556",
  "number": "111-2223334-4445556",
  "status": { ... },
  "items": [ ... ],
  "dates": { ... },
  ...
}

The delivery arrives as a POST request with these headers:

Header	Always present	Description
`ecartapi-key`	Yes	HMAC-SHA256 signature to verify the delivery came from EcartAPI.
`Authorization`	Only if `auth` was set	The exact value you provided as `auth` when creating the webhook.

Identifying which store and event triggered the webhook

Since the body is the raw resource object with no metadata, use your webhook URL to carry the context. Encode the customer, resource, and action in the path when you register each subscription:

https://yourdomain.com/webhooks/{your_customer_id}/orders/create
https://yourdomain.com/webhooks/{your_customer_id}/orders/update
https://yourdomain.com/webhooks/{your_customer_id}/products/update

Your server reads the path segments to know which customer, resource, and action triggered the delivery — no parsing of the body is needed to route the event.

The store_id you receive in the OAuth redirect is another reliable identifier and can serve as {your_customer_id} directly — it is stable across store reconnections.

Signature validation

Every delivery includes an ecartapi-key header you can use to verify the request came from EcartAPI. See Validating a webhook signature for the full algorithm and code examples.

The signature is an HMAC-SHA256 (Base64-encoded) computed over:

encodeURIComponent(url) & encodeURIComponent(body) & encodeURIComponent(shop_key)

where shop_key is the store's access token and url is the exact destination URL of the delivery.

The `auth` field

When a webhook has an auth value, EcartAPI sends it as the Authorization header with every delivery — exactly as you set it, with no Bearer prefix or other modification. Your server can then check this header to confirm the request is from EcartAPI.

Important: The auth value is write-only. It is not returned by GET requests on the webhook. Save it when you create the webhook.

Delivery and retries

Parameter	Value
HTTP method	`POST`
Expected response	`HTTP 200`
Timeout per attempt	10 seconds
Retry attempts	3 total
Interval between retries	3 hours

If your endpoint does not return HTTP 200 within 10 seconds, EcartAPI marks the delivery as failed and retries up to 3 times with a 3-hour wait between each attempt. After the third failure, no further retries occur.

Keep your webhook handler fast: acknowledge the delivery immediately with a 200 response and process the payload asynchronously.

IP allowlist

If your server restricts inbound traffic by IP, allow the following EcartAPI delivery IPs:

3.209.100.219
34.224.235.111
3.211.106.119
35.173.225.189

Billing

Operation	Billable?
Webhook delivery (POST to your URL)	No — always free
Create / update / delete a webhook record	Yes — counts as 1 request each
List webhooks (GET /api/v2/webhooks)	Yes — counts as 1 request

Deliveries do not count toward your monthly quota no matter how many fire. Only the API calls that manage webhook records count.

→ Validating a webhook signature — Code examples for verifying the ecartapi-key header.
→ Billing and request counting — How monthly quotas, pagination, and errors affect your usage.
→ Limits — Platform-level rate limits that can affect downstream webhook data.