Webhooks

5 min

Webhooks tell your system when something changes in Expressoft. You don't have to poll the API.

How it works

You give Expressoft the URL of an endpoint on your side (urlPath). In sandbox you do it with a GraphQL mutation (miscellaneous.webHooks).

Each time the event happens, Expressoft sends a message with a JSON body to that URL.

Your endpoint answers with a 2xx status code.

If your endpoint doesn't answer with 2xx, Expressoft retries two more times, 5 seconds apart. Then it stops. A missed event isn't sent again.

Sandbox and production

⚠️ WARNING In sandbox, you set a webhook yourself with a GraphQL mutation (see each event page). In production, Expressoft representatives configure webhooks for you. Contact [email protected] and send the events you need and your callback URL.

Events

Event	When it fires
Location Availability Changed	A location becomes available or unavailable for delivery orders.
Location Preparation Time Changed	The preparation time of a location changes.
Order Status Changed	The status of an order changes.
Order Transferred	An order is transferred to another location.
Product Stock Availability Changed	Products become available or unavailable at a location.

Set a webhook in sandbox

Each webhook has its own mutation under miscellaneous.webHooks. Every mutation takes your urlPath and the identifiers of the event. Open the event page for the exact mutation, variables and payload.

💡 TIP Make your endpoint fast and reliable. Answer 2xx first, then process the event in the background. A slow or failing endpoint causes missed events.

🔶 TO CONFIRM (remove before publishing) The mutations don't create a permanent subscription, but Expressoft sends a message each time the event happens. Document how long a configured URL stays active (for example for one order, or until a given time).

🔶 TO CONFIRM (remove before publishing) The Postman page doesn't state the HTTP method or the headers of the message, or whether it can be signed. Confirm them with the dev team.