Skip to main content

Set up webhooks

Let ShopLinkr send a message to your own system as soon as something changes, such as a new order.

With webhooks, ShopLinkr sends a message to your own system as soon as something changes, for example when a new order comes in or a shipment is created. Your system no longer needs to keep asking the API whether anything is new. Webhooks are intended for developers and technical partners who build their own integration.

Add an endpoint

  1. Go to Settings > Webhooks.

  2. Click Add endpoint.

  3. Give the endpoint a recognizable name, for example "ERP integration".

  4. Enter the URL where ShopLinkr sends the messages. This must be a public https address.

  5. Under Events, choose which events you want to receive. The events are grouped, for example by orders, shipments, picklists, returns and products.

  6. Click Add endpoint at the bottom.

  7. Copy the secret you see next and store it safely. You can show it again later.

Which events exist and what each message contains is described in the API documentation under Webhook types.

Secret and signature

Every message is signed with the secret of the endpoint. This lets you check that a message really comes from ShopLinkr and was not changed on the way. How to verify the signature is explained in the API documentation on webhooks.

  • Show secret - View the secret again on the page of the endpoint.

  • New secret - Create a new secret. The old one stops working right away, so update your receiver immediately.

Send a test event

On the page of the endpoint, click Send test event. ShopLinkr then sends a webhook.test to your URL right away, with one attempt. You immediately see whether it worked, with the status code and how long it took. The test event also shows up under the deliveries.

What your receiver needs to do

  • The connection must be established within 1 second.

  • Respond within 5 seconds with a status code in the 200 range. What you return in the body does not matter.

  • Do the actual work afterwards, for example through a queue. A timeout counts as a failure.

  • We do not follow redirects, a redirect also counts as a failure.

  • Messages do not always arrive in order and, very rarely, arrive twice. Use the webhook-id header to recognize duplicate messages.

Deliveries

At the bottom of the page of the endpoint you find the deliveries: every message sent to the endpoint, with the event, the number of attempts, the response of your system, the duration and the time of the last attempt. Deliveries stay visible for 30 days.

StatusDescription
PendingThe delivery is ready to be sent.
WaitingThe endpoint is paused. The delivery is still sent as soon as the endpoint works again.
SucceededYour system received the message.
FailedThe message did not arrive after 11 attempts, or your system returned 410 Gone. Use Resend to send the delivery once more.
CancelledThe delivery was not sent, for example because the endpoint was deactivated or the order was deleted in the meantime.

When your system is unreachable

When a delivery fails, ShopLinkr pauses the endpoint. New messages are not lost, but get the status Waiting. ShopLinkr retries one waiting delivery at a time: after 30 seconds, 5 minutes, 30 minutes and 1, 2, 5, 10, 15, 20 and 24 hours. When that works, all waiting messages are still sent, in order.

  • After 1 hour of pause, the primary user of your account receives an email.

  • If the endpoint still does not work after 24 hours, we deactivate it. The waiting messages are then cancelled and the primary user receives another email.

  • If your system returns 410 Gone, we deactivate the endpoint right away.

Fixed the problem? Send a test event, or resend a failed delivery. When that works, the endpoint resumes right away and you do not have to wait for the next attempt.

Activate an endpoint again

You turn a deactivated endpoint back on with Activate, on the page of the endpoint or in the overview. First check with a test event that your receiver works. Messages from the period the endpoint was deactivated are not sent afterwards. Fetch them through the API if you need them.

Want to turn an endpoint off yourself for a while? Click Edit endpoint and switch off Active.

Good to know

  • You can add up to 10 endpoints, and every URL once.

  • Only public https addresses on port 443 are allowed. We refuse IP addresses, localhost and addresses in an internal network.

  • We send at most 5 messages per second per endpoint.

  • You manage webhooks in the dashboard only. By default, only the Administrator role has access.

Related

API overview

Create API token

Last updated on

Job Jenniskens

Written by

Job Jenniskens, Founder

Started ShopLinkr from his own webshop. Still builds on the platform every day and knows every corner of the code.

LinkedIn

Still have questions?

We are happy to help. Send a message or book a call.