# Webhooks

> Receive signed HTTPS notifications when conversations, handoffs, leads, orders and other events happen in ShopAssist.

Source: https://shopassist.coec.dk/docs/webhooks · Updated 2026-10-01

*(Growth and up)*

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 [#create]

1. Open **Developers → Webhooks** in your organization and click **Add endpoint**. You need an admin or owner role and a recent sign-in.
2. Enter an HTTPS URL on port 443 that is reachable from the internet, choose the [event types](/docs/webhooks/events) and optionally limit the endpoint to some stores.
3. Copy the signing secret (`whsec_…`). It is shown once.
4. Send a [test event](/docs/webhooks/testing) and check that your endpoint answers `2xx`.

An organization can have up to 20 endpoints.

[Open API keys](/app/go/developers)

## Envelope [#envelope]

Every delivery has the same JSON envelope:

```json
{
  "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](/docs/webhooks/events).

## Headers [#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](/docs/webhooks/verifying-signatures) |

## Responding [#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 [#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 [#event-log]

Events of the last 30 days can also be read with the [events API](/docs/api/reference/events/list-events), for example to catch up after an outage.