Webhooks
About webhooks
Webhooks are callbacks to your own system/environment, allowing you to get notified about specific events that happen in other solutions, like Cargosnap. Such events may trigger specific functionality on your own system, nearly at the same time they happen in the system where the event originates (e.g. instead of 'polling' the other system, the information gets pushed to you).
In 'global settings', any paid account can set up webhooks on a per-event basis. Our webhooks are HTTPS POST requests, with a JSON payload. The payload (as described in the next sections) depends on the trigger event.
Securing webhooks
Webhooks must be secured: you are opening a port in your environment where data gets posted to.
Cargosnap supports 'shared secret' authentication, but we do not check if you use it. Do use it!
To authenticate a payload, make sure the webhook contains a secret that only you know and is used for this specific use case.
There are two common patterns we support: "basic authentication" and "query parameter":
Basic authentication
Basic authentication is a secure manner to add authentication to your endpoint. It is supported by most backends and easy to set up. It is based on a username and password combination. You can implement it on our webhook by setting the username and password in the webhook URL, following this structure:
https://username:password@mywebhookendpoint.example.com/wbhk/cargosnap
Based on this, we will send the username and password as basic authentication parameters in the heading of our POST call (Basic auth will thus add a parameter "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" to the header, where that later part is the base64 encoded username/password you provided us).
Query parameter
As an alternative to that you may include a token in the URL parameters of the endpoint, for example:
https://mywebhookendpoint.example.com/wbhk/cargosnap/?token=fwe33fG35ghr3wdb3t62eG4tgA1KI
Note how this webhook contains a strong token. We put this token in each webhook, thus allowing you to validate the payload indeed originated from us.
-Of course- make sure your endpoint is HTTPS only!
IP filtering
In case you want to apply IP filtering on incoming webhooks, note that we may use different IP addresses over time to send out the payload to you system, making filtering potentially breaking upon IP address changes, so we recommend against it. If filtering is required, then use a reverse lookup against the host "out.cargosnap.com" to lookup the permitted IP address.
Sanitizing webhooks
After authenticating the webhook, make sure you sanitize the payload. This involves validating the format of the payload and filtering for the specific data you are interested in. Do not assume your data is always present: just imagine someone posts a "snap" payload towards the endpoint made for "forms".
Error handling
We send the webhook per the trigger event. But what if you're just ... just having that one minute (maintenance) outage at that moment? Well not to worry, our webhook will retry 2 times, with some time in between. So good chance we're good there. Should the downtime be a bit longer or something in our payload causes your end to fail (e.g. returning a 500 response), we will then email a warning to the administrator of the webhook, including the payload. This allows you to stay aware of issues, but also to never loose any data.
Should your endpoint keep generating errors, we will auto-pause the webhook for you. This is done after 1000 consecutive error responses. See below what pause does.
Pausing a webhook
You may pauze a webhook. E.g. in case you are performing maintenance on your endpoint. We will not send (but also not hold!) any events in that period. It will avoid triggering emails as well as errors in your and our logs.
Testing webhooks
Tip: we like https://webhook.site for testing webhooks, its free and easy to use. You may like it too!