Events and webhooks

Some things should not wait for tonight. An order needs to reach the ERP now, a warehouse needs to know about a shipment now, and a CRM wants to know that a new organisation exists. Events are how the platform says "this happened", and webhooks are how another system hears it.

Events, subscriptions and webhooks

An event is a record that something happened here: order.placed, product.published, organisation.created. It carries what happened, when, and the identifier of the thing it happened to.

A subscription connects an event to a reaction: a workflow that runs, or a webhook that fires.

A webhook is an HTTP call that crosses the boundary. Outbound webhooks push a platform event to a URL you own; inbound webhooks let an external system push into a workflow here. Either way it is a push: the receiver is told instead of polling.

The distinction that matters in practice: an event is a fact, a webhook is a delivery attempt. Deliveries fail, regularly, and everything below is about that.

Set up a webhook

1. Open Events › Event Catalog to see which events exist and what each one carries. Decide from the catalog rather than from a guess at the name.
2. Go to Webhooks › Outbound and create a subscription.
3. Choose the events to subscribe to. Subscribe narrowly. A receiver that gets every event and ignores most of them is a receiver that will one day process one it should have ignored.
4. Enter the endpoint URL. HTTPS, and an address that belongs to a system, not to a person's laptop.
5. Set authentication: a shared secret, a signing key or a bearer token, whatever the receiver expects.
6. Set the retry policy. Several attempts with growing gaps is the sane default: a receiver that is restarting should not cost you the message.
7. Send a test event and confirm the receiver acknowledges it with a 2xx.
8. Activate.

Rules for the receiving side

You often do not control the receiver, but you can insist on these, in writing:

• Acknowledge fast, process later. The receiver should accept the payload, answer 200, and do the work afterwards. A receiver that does five seconds of ERP work before answering will time out under load and cause retries that make the load worse.
• Deduplicate on the event ID. Retries mean the same event can arrive twice. The receiver must treat a repeat as a no-op. Without this, a retried order.placed becomes a second delivery.
• Do not rely on order of arrival. Two events fired a second apart can arrive in either order. If sequence matters, read the timestamp in the payload.
• Verify the signature. An endpoint that accepts any POST accepts anyone's POST.

What to check

• The delivery log under Webhooks › Outbound. Each attempt with its response code and duration. Persistent 4xx means your payload or your credentials are wrong; persistent 5xx means their system is. A slow-but-successful endpoint is a warning: it will start timing out on your busiest day.
• The failed queue. Events that exhausted their retries. This should be empty. If it is not, somebody has to decide whether to replay them, and that decision has a deadline attached.
• Volume in Events › Event Stream. An event count that jumps tenfold usually means a bulk operation fired per-record events, for instance a bulk edit across 30,000 products. Better to know that before the receiver finds out.

When to use an event and when not to

The rule of thumb: events are for things that happened, one at a time, where latency matters. Bulk data movement stays a scheduled workflow.

Next

• Monitor your syncs: watching deliveries and runs together.
• Common sync errors: reading the failures.