CRM change webhooks

CRM webhooks tell your systems about changes in a store's CRM as they happen: a new contact, a stage change, a completed task, a new lead. Each event is posted as JSON to your HTTPS endpoint and signed with that endpoint's own secret. Payloads carry ids, stage keys and the names of the fields that changed, never personal details. To read the values, your receiver calls the merchant CRM API.

Set up an endpointCopy Anchor Link

In the store admin, go to Settings → CRM → Webhooks and add an endpoint with its URL, the events it wants and a description.

• The URL must be https:// and must resolve to a public address. Private, loopback and reserved addresses are refused, as is a name that does not resolve.
• A store can have up to 20 endpoints.
• Each endpoint has its own signing secret, starting whsec_. It is shown once, when the endpoint is created. Copy it into your receiver's configuration straight away.
• New secret makes a new one, shown once. The old secret stops working at once, so update your receiver at the same time.
• Send a test sends one signed webhook.test event now.
• Switch off pauses an endpoint: changes send nothing to it until you switch it back on.

The signing secret is per endpoint. It is never the store's API secret.

EventsCopy Anchor Link

• actor.type says who made the change: staff, system, ai, import, flow, api or merge.
• changed holds field names: first_name, last_name, title, email, phone, lifecycle_stage, owner, company, tags and custom.{key} for contacts; name, domains, address_*, industry, size and is_sole_trader for companies.
• from and to are stage keys, such as lead and customer.
• records lists what a task is about, such as contact:12.

The payloadCopy Anchor Link

Every event has the same envelope:

{
  "id": "01JB3K8Q2V7N4M6P9R1T3W5Y7Z",
  "type": "contact.updated",
  "created_at": "2026-10-24T09:30:00+00:00",
  "store": "hearth-and-oak",
  "api_version": "2026-10-01",
  "data": {
    "object": "contact",
    "id": 12,
    "changed": ["email", "lifecycle_stage"],
    "actor": { "type": "api" }
  }
}

Never sent: names, email addresses, phone numbers, postal addresses, custom field values, tag values, note or task text, or message content. A sensitive custom field's name can appear in changed, but its value never does.

HeadersCopy Anchor Link

A staging store signs with its own endpoint secrets. If one receiver serves both, use X-ElaraOne-Environment to keep test events out of live data.

Handle an eventCopy Anchor Link

1. Read the raw body and verify the signature. Refuse anything that fails.
2. Skip the event if you have already processed its X-ElaraOne-Delivery.
3. Answer 2xx straight away. Each attempt times out after 10 seconds, and redirects are not followed.
4. Do the work afterwards, on a queue: fetch the record through the merchant CRM API and update your system.

const res = await fetch(`https://api.elaraone.app/api/v1/merchant/crm/contacts/${event.data.id}`, {
  headers: {
    Accept: 'application/json',
    'X-Tenant-Key': process.env.ELARAONE_TENANT_KEY!,
    'X-Tenant-Secret': process.env.ELARAONE_TENANT_SECRET!,
    Authorization: `Bearer ${process.env.ELARAONE_MERCHANT_KEY}`, // a key with crm:read
  },
})

The API checks the key's access, so your copy is only as complete as the key allows. A contact that has been merged into another answers 404; follow contact.merged to the contact that stays. On contact.erased, delete everything you hold about that contact id.

Events for one record usually arrive in order, but a retry can overtake a later event. Use created_at, or simply read the record's current state through the API, rather than trusting arrival order.