Setting Up Webhooks

What Webhooks Do

A webhook is an automatic message that Helm sends to another system when something happens in your warehouse. Instead of your ERP, accounting package or customer service tool repeatedly asking Helm for news, Helm tells it: an order has been despatched, stock has changed, a delivery has arrived.

Helm collects the events for each webhook and sends them together on a regular cycle that you choose, from every minute to every hour. That keeps every system your business runs on working from the same up-to-date picture, without anybody copying information across by hand.

Example: your accounts team raises an invoice every time an order leaves the building. You set up an Order Despatched webhook on a 10 minute cycle. Every 10 minutes, Helm sends your accounting system the orders despatched since the last send, the invoices are raised automatically, and nobody has to export a despatch list at the end of the day.

Setting up the Helm side takes a few minutes and needs no code. The system receiving the webhook does need to be ready to accept it, so you will usually set this up alongside whoever looks after that system, such as your developer or integration partner.

Before You Start

• A URL to send to. This is the internet address of the receiving system. Your developer or integration partner will give it to you, along with whether it expects a POST or PUT request. It must be reachable from the internet, because Helm sends from its own servers rather than from inside your office network.

• Authentication details, if the receiving system needs them. That might be a username and password, a token, or a signing secret. Have them to hand before you start.

• Access to System Settings. Webhooks live under Settings > System Settings. If you cannot see Webhooks there, ask whoever administers Helm for your business to check your permission group (see User Permission Groups).

• One event per webhook. Each webhook listens for a single event. To send several events, for example both Order Created and Order Despatched, create one webhook for each. They can all point at the same URL.

• Your warehousing mode. Pick, Movement and Stock at Location Updated events appear in the event list on accounts running outside Basic mode, because those modes use picks and stock locations. See Understanding Warehousing Modes in Helm for the difference.

Events You Can Send

Choose the event that matches the moment the receiving system needs to hear about.

The two stock events do different jobs. Available Stock Updated fires when the quantity you can sell changes, which is what a sales channel or website usually needs. Stock at Location Updated fires when physical stock changes at a location, including moves between locations that leave the sellable total the same.

How to Create a Webhook in Helm

Creating a webhook takes two steps: the connection details, then who should be emailed if something goes wrong.

Step 1: Connection Details

1. Go to Settings > System Settings > Webhooks.

2. Click Create Webhook. The Add New Webhook window opens.

3. Fill in the details:

   1. Name: name it after the system at the other end and what it receives, such as "Despatched orders to accounts", so the list stays easy to read later.

   2. Event: choose the event that should trigger the webhook. Type in the search box to find it quickly.

   3. Method: choose POST or PUT, whichever the receiving system expects. POST is selected by default and is the most common.

   4. Interval: choose how often Helm sends the events it has collected: 1 minute, 10 minutes, 30 minutes or 1 hour. 30 minutes is selected by default. The Interval also sets how quickly Helm tries again if a send fails, so choose it deliberately (see Choosing an Interval below).

   5. URL: paste the full address of the receiving system, starting with https://.

4. Set the authentication method, if the receiving system needs one. Open Authentication method and choose one scheme. Whatever you choose is applied to every webhook request sent to this URL.

   1. None: no credentials are sent. Use this only if the receiving system has told you it does not need any.

   2. Basic Auth: enter the Username and Password the receiving system gave you.

   3. Bearer Token: enter the Token the receiving system gave you.

   4. HMAC Signature: Helm signs every request with a secret that only you and the receiving system know, so it can check each message genuinely came from Helm and was not changed on the way. Enter the Signing secret, then check that the Signature header name (X-Webhook-Signature by default) and the Algorithm (sha1, sha256 or sha512) match what the receiving system expects. Turn on Include timestamp if it asks for one.

5. Add custom headers, if needed. Open Headers and click + to add a row, then enter the Header name and its Value. Some systems ask for an extra header such as an account ID. Use the bin icon to remove a row you no longer need.

6. Check Helm can reach the URL. Click Test Ping URL. Helm sends a short test message using the details you have entered and tells you whether the receiving system answered. If it fails, check the URL and credentials with whoever gave them to you.

7. Click Continue.

Step 2: Failure Notifications

1. In Notification Emails, type the email address of each person who should hear about problems with this webhook, pressing Enter after each one. A shared team inbox works well here.

2. Choose which emails they receive:

   1. Receive an email upon the failure of a single job. Off by default. Turning it on gives you the earliest warning that something needs attention.

   2. Receive an email when your webhook is deactivated after repeated failures. On by default. Leave it on.

3. Click Create Webhook. The webhook appears in your Webhooks list and is active straight away.

Example: Sending Despatched Orders to Your Accounting System

1. Your accounting system's developer gives you a URL, https://accounts.example.com/helm/despatched, and a token to authenticate with.

2. You go to Settings > System Settings > Webhooks and click Create Webhook.

3. You name it "Despatched orders to accounts", choose the Order Despatched event, leave the method as POST, set the Interval to 10 minutes and paste in the URL.

4. Under Authentication method, you choose Bearer Token and paste in the token.

5. You click Test Ping URL, see that the accounting system answered, and click Continue.

6. You add accounts@yourcompany.co.uk to Notification Emails, turn on the single job failure email, and click Create Webhook.

7. That afternoon the warehouse despatches 40 orders. Every 10 minutes, the accounting system receives the orders despatched since the last send and raises their invoices.

Checking & Managing Your Webhooks

Every webhook you create is listed on the Webhooks screen. Use the search box or Filters to find one, then open the actions menu on its row to work with it.

• Jobs: every send is recorded as a job, showing whether it is Pending, Succeeded or Failed. Choose View Logs on a job to see each attempt and exactly what was sent and received. This is the first place to look if someone says information has stopped arriving.

• Test: pings the saved webhook with its stored details, so you can check the receiving system is answering without reopening the form.

• Edit Webhook: change any of the settings. Saved passwords, tokens and secrets show masked; leave them as they are to keep them, or type over them to change them.

When a Send Fails

If the receiving system does not accept a send, Helm tries again once per Interval, up to 10 times. Nothing is lost while it does: once the receiving system is working again, the waiting events go out with the next send automatically.

If a webhook keeps failing over a long period, Helm deactivates it and its status shows as Auto Disabled. Fix the problem at the receiving end first, check it with Test, then switch the webhook back to active.

Best Practices & Notes

Choosing an Interval

Use a shorter Interval for events the other system needs quickly, such as despatches feeding a customer notification. Use a longer one for busy events like Order Updated or the stock events: if the same order changes six times within one Interval, it is sent once, in its latest state, which keeps the receiving system from being flooded. Remember that the Interval is also the gap between retries, so a longer Interval means a failed send takes longer to recover.

Test With a Real Event

A successful ping proves Helm can reach the URL. To prove the whole flow works, trigger the event once yourself, for example by despatching a test order, and ask the receiving side to confirm the information arrived and looked right.

Expect the Occasional Repeat

Because Helm retries failed sends, the receiving system may occasionally see the same order or product twice. Ask whoever built it to treat a repeat as an update to the same record rather than a new one.

Keep Credentials in Step

If the receiving system changes its password, token or signing secret, update the webhook in Helm at the same time, so sends keep being accepted.

FAQ

I have just created a webhook. Why has nothing arrived yet?

Helm sends on the webhook's Interval, so allow one full Interval after the event happens. Check too that the webhook is active and that the event has actually happened since you created it.

Why did one send contain several orders?

That is the Interval at work. Everything collected since the last send goes out together.

Can one webhook send more than one event?

Each webhook sends one event. Create a separate webhook for each event you need; they can all use the same URL and authentication.

Why can't I see Pick, Movement or Stock at Location Updated events?

These events are available on accounts running outside Basic mode. See Understanding Warehousing Modes in Helm.

Should I choose POST or PUT?

Use whichever the receiving system's documentation asks for. If it does not say, POST is the usual choice.

Do I need a developer?

Not for the Helm side, which is all set up from this screen. The receiving system does need to be built to accept webhooks, so involve whoever looks after it.

If a webhook is not arriving where you expect, contact the Helm support team with the webhook's name and the date of a failed job, and we will help you find out why.