A webhook is a technical feature that can be used to send data in real time. Webhooks are useful for updating information in different locations without manual intervention.
|
Please note that this feature is an optional add-on included in certain pricing plans but can also be purchased separately. The cost is 350 SEK/month and will be added to your upcoming invoice. |
Introduction
AM System’s functionality for communicating with external services and systems is offered through webhooks. Webhooks are not unique to AM System but can be seen as a framework for sending and receiving data between different services and systems. Think of webhooks as an automated function that replaces the need for a person to manually transfer data from one system to another.
Webhooks consist of two components: outgoing and incoming webhooks.
Outgoing Webhook
An outgoing webhook enables the sending of specified data under certain conditions. In this outgoing webhook, you can also define a possible response from the external system. The response can then be saved in the same case that initiated the outgoing webhook.
For example, selected case and metadata can be sent to an external system that supports webhooks when a case is created. The external system can then receive this data and possibly provide a response. If the same case triggers a new webhook, the data is sent again. HOWEVER, it is up to the receiving system to handle this as an update of the data (for instance, by comparing a constant variable such as a case number), as the outgoing webhook itself does not differentiate between new and updated data.
❗ Note:
- Outgoing webhooks cannot be triggered when a case is deleted.
- If you choose to send images or files with outgoing webhooks, these will be delivered as a URL. This URL is only valid for 24 hours, so ensure you save the information if it needs to be retained permanently.
Incoming Webhook
An incoming webhook has the reverse functionality. It is a straightforward way to register cases from external services and systems into AM System and a specific form. Incoming webhooks are thus one-way communication, and each incoming webhook will create a new case.
❗ Note that incoming webhooks CANNOT:
- Provide the external system with any return response for the incoming webhook.
- Be used to ask a question such as “Give me all cases with case numbers between #28 and #36.”
- Update data in an already created case.
- Create data in sections other than the first (top section in a form).
- Trigger on deleted cases.
Activating Webhooks
Activating webhooks is straightforward as they are activated in the same way as message triggers and managed similarly.
You activate webhooks for each form under the Advanced and Add-ons » More Add-ons … » Outgoing Webhook or Incoming Webhook tab. This section also provides the information your IT department or external IT partner needs to enable webhooks.
Configuring webhooks requires more advanced technical knowledge. We recommend that you, as an administrator, contact your IT department or external IT partner when configuring webhooks in your forms unless you are already familiar with webhooks.
Technical Summary for Exploring Webhooks Yourself!
Outgoing Webhook
With the help of Activates When (When) and If the Following Conditions Are Met (If), you can combine multiple events to control when a webhook sends data.
- Under Content, select which fields from the form you want to include. You can also create custom fields to meet the receiving system’s requirements.
- Under Settings, specify settings for the external system, such as HTTP Method and Authentication Type.
| HTTP method | POST, GET, PUT |
| Webhook URL | Det externa systemets URL |
| Autentiseringstyp | Basic, ingen |
| Försök | 1, 2, 3 |
| Timeout (sek) | 10, 30, 60 |
| Protokolltyp | JSON, JSON ARRAY, FORM |
If you wish to receive response data back from the receiving system, this is possible. This is configured under the Response Data section. Choose the fields you want to update under Fields and enter the receiving system’s response key under JSON Response Key. Multiple fields and response keys can be added if needed. This “returnDataURL” is valid for 2 hours.
Incoming Webhook
To create a new case with an incoming webhook, the external system must know the URL (web address) to send all data and the “IDs” of the fields to be created.
- “Your Webhook URL” is the address the external system should use.
- “Field IDs” can be found via “Settings/Your Form” or by downloading the “Form Structure”.
Note:
- Fields must be located in the form’s first section.
- Existing cases cannot be updated.
Under “Send Directly as JSON”, you will find examples of an “HTTP post” that can be tested using a tool like cURL (a simple tool for sending “HTTP requests” via the command line). Modify “text-field” to correspond to a field ID in your form.
curl -X POST -H 'Content-type: application/json' \
--data '{"text-field": "Simple input in a text-field with id textfield"}' \
https://yourWebhookUrl
Authentication
To authenticate users, activate the “Authenticate User” option.
Create an “auth key” in cURL by entering:
curl -X POST -H 'Content-type: application/json' \
--data '{"username": "Username", "password": "Password"}' \
https://yourWebhookUrl
If the user credentials are correct, you will receive an “auth key”, which you add in the Header as “Auth-key”.
To remove an auth key:
curl -X DELETE -H 'Content-type: application/json' \
--data '{"username": "Username", "password": "Password"}' \
https://yourWebhookUrl
Validation
An incoming webhook validates that mandatory fields in the form are included in all incoming data. If you wish to bypass this check, include “skipvalidate” in the address:
https://yourWebhookUrl/skipvalidate
Triggers
If the form is configured with triggers (automatic notifications for specified events) and you don’t want these triggers to run when a webhook creates a case, include “skiptriggers” in the address:
https://yourWebhookUrl/skiptriggers
Creator
The metadata “Creator” is a mandatory field in all forms. It is automatically updated with “Addon - Incoming Webhook” and therefore does not need to be included in the JSON data.
Error Handling
If successful, you will receive the response “HTTP 200 OK” with an empty JSON object in the “body.” Otherwise, you will receive “HTTP 400 Bad Request” with a JSON object indicating what went wrong.
Common Errors:
| field_required | The field is mandatory, and data is missing. |
| access_deny | The issuer does not have permission to register in this form. |
| wrong_date | Incorrect date format. |
| value_missing | The value is missing. |
| value_not_array | The value is not an array. |
| value_not_numeric | The value is not numeric. |
Combining Options
| skipvalidate |
Validation of mandatory fields is not performed (see the Validation section). |
| skiptriggers |
Triggers are not executed (see the Triggers section). |
You can combine “skipvalidate” and “skiptriggers”:
https://yourWebhookUrl/skiptriggers/skipvalidate
Third-Party Tools
Two examples of tools that can assist in managing webhooks are:
Please note that AM System has no affiliation with these services and does not take responsibility for how they are used!
Related content:
Last updated: 22 November, 2024