Webhooks
Receive signed HTTPS notifications when conversations, handoffs, leads, orders and other events happen in ShopAssist.
ShopAssist sends an HTTPS POST to your endpoint when something happens, for example a handoff, a new lead or an attributed order. If you are reading this because you saw ShopAssist-Webhooks/1.0 in your logs: these requests come from a ShopAssist customer who configured your URL as their endpoint.
Create an endpoint
- Open Developers → Webhooks in your organization and click Add endpoint. You need an admin or owner role and a recent sign-in.
- Enter an HTTPS URL on port 443 that is reachable from the internet, choose the event types and optionally limit the endpoint to some stores.
- Copy the signing secret (
whsec_…). It is shown once. - Send a test event and check that your endpoint answers
2xx.
An organization can have up to 20 endpoints.
Open API keysEnvelope
Every delivery has the same JSON envelope:
{
"id": "evt_01k6a8x3qv6f2m9c4j7t5r0bwe",
"type": "order.attributed",
"api_version": "v1",
"created_at": "2026-10-05T10:00:00Z",
"organization_id": "org_01k5…",
"store_id": "sto_01k5…",
"data": { "order": { "id": "aor_01k6…", "order_number": "#1042", "attribution_type": "bot_add_to_cart" } }
}store_id is null for organization events such as usage.threshold_reached. The shape of data per type is in the event catalog.
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | ShopAssist-Webhooks/1.0 (+https://shopassist.coec.dk/docs/webhooks) |
ShopAssist-Event-Id | the event id (evt_…), the same on every retry |
ShopAssist-Event-Type | the event type |
Idempotency-Key | the event id |
ShopAssist-Signature | t=<unix time>,v1=<hex HMAC>; see verifying signatures |
Responding
Answer with any 2xx status within 10 seconds. Redirects are not followed and count as failures. Do the work asynchronously if it takes longer, and dedupe on ShopAssist-Event-Id: the same event may arrive more than once.
Personal data
conversation.*, message.created, handoff.*, lead.*, back_in_stock.* and csat.submitted carry personal data of your shoppers (names, emails, messages). You are responsible for the data once it reaches your endpoint. Subscribe only to the events you need.
Event log
Events of the last 30 days can also be read with the events API, for example to catch up after an outage.
Last updated on