Automations

How to set up webhooks in easySales: send orders, AWBs and stock changes to your systems

How to set up webhooks in easySales: send orders, AWBs and stock changes to your systems

Send easySales events such as new orders, AWBs, invoices and stock changes to your own systems the moment they happen, and keep the subscriptions working.

What webhooks do

A webhook tells another system the moment something happens in easySales. When an order arrives, an AWB is created or a stock level changes, easySales sends the details to an address you choose, so your ERP, accounting tool or online shop can react straight away instead of asking easySales every few minutes.

Open the page at easy-sales.com/webhooks while you are signed in. Each line on it is a subscription: one event, sent to one address.

Three things to know first:

  • The receiving address must be built by you or your developer. easySales sends the data; the system at that address decides what to do with it.
  • A subscription that keeps failing switches itself off. After 100 failed attempts easySales stops sending and e-mails you. It does not switch back on by itself.
  • Events are not kept while a subscription is off. When you turn it back on, sending starts again from that moment.

Subscribe to an event

The Webhooks page: Subscribe to webhook, and four subscriptions grouped by event: Order created and Order updated with Success, Invoice created with Failed, and Product stock updated with Failed and the Enable button, each with its URL, secret, method and More details.
One subscription per event and address.
  1. Press Subscribe to webhook.
  2. In Url, enter the address that will receive the data. Use an https address.
  3. Leave HTTP method on POST.
  4. In Webhook, choose the event.
  5. In Secret, enter a key of at least 24 characters. Your system uses it to check that the data really comes from easySales.
  6. Press Save.

The subscription appears under the name of its event. To send the same event to a second system, subscribe again with the other address. One address can be added only once for each event.

Event Sent when
Order created A new order arrives from any channel or is added by hand.
Order updated Anything changes on an order, for example its status, products or address. This event is sent often.
Awb created An AWB is generated for an order through a courier in easySales.
Delivery status updated The courier reports a new delivery status for a shipment.
Invoice created, Storno invoice created An invoice or a storno invoice is issued for an order.
Return created, Return updated A return is created, or its status, products, notes, shipments or invoices change.
Product created, Product updated A product is added or changed, including its price.
Product stock updated A product's stock changes.
Category created / updated, Characteristic created / updated A category or a characteristic is added or changed.
Products refresh requested, Stock refresh requested A refresh of products or stock is requested for an online shop.
Ticket created, Ticket updated A conversation with a buyer starts in Customers → Tickets, or changes.
Account suspended, Account activated The easySales account is suspended or activated again.
Events you can subscribe to

Follow what was sent

An Invoice created subscription with More details open: the invoice data sent as payload, and the response Service Unavailable with the badges Attempt 2 of 3, the next attempt time and the status code 503.
The last event sent and what your address answered.

Each subscription shows Success or Failed for the last event sent, and when it was sent. Press More details... to see that event:

  • Payload is the data easySales sent.
  • Response is what your address answered, with its status code.
  • Attempt 2 of 3 | Next attempt: … means the event failed and will be sent again. Final attempt has been made means there are no more tries for that event.

Only the last event of each subscription is shown here.

Change, pause or remove a subscription

The webhook form with Url, HTTP method POST, Webhook Invoice created, Secret and Save.
Address, method, event and secret.
  • Edit changes the address, the HTTP method or the secret. To send a different event, subscribe to that event and remove the old subscription.
  • Disable pauses the subscription and Enable starts it again. Nothing is sent while it is paused, and the events from that time are not sent later.
  • Unsubscribe removes the subscription at once.

What your system needs to do

Detail
Format JSON, with the event data under payload and the subscription id and event name under webhook.
Signature The Signature header holds an HMAC-SHA256 of the body, made with your secret. Compute it on the body exactly as received.
Answer Any 2xx status within 3 seconds. Answer first and process the data afterwards.
Certificate https addresses must have a valid certificate.
Retries Three tries per event: the second about 10 seconds after the first, the third about 100 seconds later.
Order of arrival Because of retries, events can arrive out of order. Use the data in the payload, not the arrival time.
What easySales sends and expects

When a subscription switches itself off

Every failed try counts: an error answer, no answer within 3 seconds, or a certificate problem. After 100 failed tries the subscription is switched off and you receive the e-mail "Webhook has been disabled". Its View webhooks button opens this page.

  1. Fix the problem at the receiving address.
  2. Press Enable on the subscription.
  3. Fetch the changes you missed through the easySales API, for example the orders changed during that time.
📖
Read next
How to connect to the easySales API: OAuth clients and personal access tokens
Create OAuth clients and personal access tokens for the easySales API, choose the right grant type and scopes, and keep your connections from logging each other out.
→
📖
Read next
How to connect a custom shop to easySales with the API
Connect any custom or unsupported shop platform to easySales through the API: the two credentials you need, pushing products and stock, sending orders, and getting changes back.
→

Your team and webhooks

A team member needs the View webhooks permission to open the page. With it, they can add, change, pause and remove subscriptions.

When something does not look right

Symptom What to do
Nothing arrives any more and the subscription shows Enable It was switched off after repeated failures. Fix the address, press Enable, then fetch the missed changes through the API.
The last event shows Failed Open More details... and check the status code and the answer of your address.
"The secret must be at least 24 characters." Enter a secret of 24 characters or more.
"The url has already been taken." That address already receives this event. Edit the existing subscription instead.
Storno invoices are not received Subscribe to Storno invoice created; Invoice created covers regular invoices only.
The receiving system is flooded with order updates Order updated is sent for every change. Answer quickly and process the data in the background.
Common problems

Frequently asked questions

Open easy-sales.com/webhooks while you are signed in. The "Webhook has been disabled" e-mail also links to it.

After 100 failed attempts easySales switches the subscription off and e-mails you. Fix the receiving address and press Enable.

No. Fetch the changes from that time through the easySales API.

Compute an HMAC-SHA256 of the body with your secret and compare it with the Signature header.

Within 3 seconds, with a 2xx status. Otherwise the attempt counts as failed and is tried again.

Yes, with the View webhooks permission.

Was this guide helpful?