Webhooks: setup and verifying the origin of calls

A webhook is a message that Quanda itself sends to the address of your system when an event happens, for example a link click, an email open, an unsubscribe, an email being sent or a completed survey being saved. You manage webhooks in Quanda under Settings / Webhook. Each webhook can carry a custom header with a secret token, which your system uses to verify that the call really came from Quanda.

How to add and edit a webhook

You will find the list of webhooks under Settings / Webhook. In the dialog for adding and editing a webhook you enter the address Quanda should send calls to and the event that triggers the webhook.

The dialog also contains optional fields for a custom header:

• Header name: the name under which Quanda adds the value to the call, for example X-Webhook-Token.
• Header value: the secret token your system compares with its stored value. For a saved webhook the field shows only a mask.
• Remove header: an option shown for a webhook that has a header. After you save, Quanda stops adding the header to calls.

You can leave both fields empty. The webhook then works the same as before.

What the lock icon in the list of webhooks means

The lock icon in the list marks a webhook secured with a custom header. A webhook without a lock has no header and Quanda calls it without one.

Verifying the origin of calls with a custom header

A header is an additional piece of an HTTP request in the form of a name and a value. It is sent along with the call but is not part of its content. A token is a random string of characters known only to you and Quanda, and it works much like a password.

A webhook call without a header contains nothing that would tell the recipient who sent it. Anyone who knows the address can send a forged call to it. A custom header prevents that.

How it works

Quanda adds the header you set to every call of the webhook. Your system compares the header value with the value it has stored and processes the call only when they match.

Use a random string of at least 32 characters as the token and do not use it anywhere other than for Quanda. Reject calls without the correct header in your system with a status 401 response.

The content of the call, that is its body, does not change. The feature is optional and webhooks without a header work exactly as before.

How to set the header

1. In Quanda, open Settings / Webhook.
2. Add a new webhook or open an existing one for editing.
3. Check that the webhook address starts with https://.
4. Enter a name in the Header name field, for example X-Webhook-Token.
5. Paste the secret token into the Header value field.
6. Save the webhook. A lock icon appears next to it in the list.

Store the token in your own system before you save the webhook. Quanda never shows the saved value again.

How to change or remove the header

• Editing a webhook without changing the header: leave the Header value field empty. The header stays as it is saved.
• Changing the token: enter a new value in the Header value field and save the webhook. The new value applies from the next call, so change it in your system at the same moment.
• Removing the header: choose Remove header and save the webhook. The lock icon disappears from the list.

Conditions and limits

• An https:// address: the https protocol transfers data encrypted. A webhook with a header must have an address starting with https:// and the target server must have a valid certificate. Quanda does not send the header to an unencrypted address.
• Header name: may contain letters, digits and hyphens and have at most 64 characters. The Authorization header is allowed. Some technical names are not allowed, for example Host, Content-Type, Cookie and names starting with X-Quanda-.
• Header value: may contain printable characters without diacritics and have at most 1024 characters.
• Number of headers: in the app you set one header per webhook, through the API up to 5. A webhook with several headers set through the API does not show the header fields in the app and you edit it through the API.
• Displaying the value: the saved value is shown neither in the app nor in the API. You only see a mask, that is four asterisks and the last 4 characters. For values shorter than 12 characters you only see asterisks.

How Quanda delivers webhooks

Your system should answer a call with status 200. After any other response Quanda repeats the call, up to 5 times:

1. after 30 seconds,
2. after 5 minutes,
3. after 50 minutes,
4. after approximately 8 hours,
5. after approximately 83 hours.

Quanda proceeds the same way when your system rejects a call because of the header. A custom header does not change delivery.

Documentation for developers

You can also create and edit webhooks through the API. Headers are set in the headers field when creating and editing a webhook, that is in POST, PUT and PATCH calls to /api/webhook/webhooks/. Editing a webhook without any change with a PUT call no longer returns an error, and a partial edit with a PATCH call does not require the event field.

All calls and message structures are described in the API documentation, Webhooks section. How to get an API key is covered in the article API documentation and API key.

The custom header is available at no extra charge to all accounts with access to Settings / Webhook and to the API.

If you are not sure what to do or have a question, do not hesitate to contact our customer support at support@onquanda.com or on the phone number +420 605 163 892.