Webhook Options
Send OttoFMS webhooks with any HTTP method, and customize the payload with query parameters and headers, and choose how incoming requests are authenticated.
The webhook payload can be customized to include more information about the webhook request.
HTTP Methods
Webhooks can be sent using any HTTP method — POST, GET, PUT, PATCH, DELETE, and so on. This means you can point a third party service at your webhook URL without worrying about which method it uses, and you can use the webhook receiver as a simple REST-style endpoint.
A few things to keep in mind:
GETrequests do not have a body, so the payload sent to the OttoReceiver script is built from the query parameters. See URL Query Parameters below.- Methods that do have a body are all handled the same way: the JSON body becomes the payload.
- If you include the headers in the payload with
includeHeaders, the request method is added as theX-Methodheader, so your script can branch on it.
PATCH and DELETE support (and the X-Method header) were added in OttoFMS
4.12.0.
URL Query Parameters
Query parameters can be added to the webhook url to include more information. The query parameters can be used in two ways:
-
By default, the query parameters are sent through to the OttoReceiver script as the script parameter. You can retrieve the query parameters in the script using a
Get(ScriptParameter)function. -
You can optionally include the query parameters in the webhook payload by including the "includeQuery" query parameter in the webhook url. This will include the query parameters in the webhook payload at the "request-query" key as follows:
{
"request-query": {
"query-parameter-name": "query-parameter-value"
},
"rest-of-payload":{
...
}
}- Query parameters are included in the webhook payload by default when using a GET request to send the webhook.
The "includeQuery", "includeHeaders", and "apiKey" query parameters are not included in the query params that are passed to the OttoReceiver script.
includeQuery only works when the request body is a plain JSON object ({}).
If the body is a JSON array ([]) or any other type, the query parameters
will not be merged into the payload.
Request Headers
You can optionally include the headers in the webhook payload by including the "includeHeaders" query parameter in the webhook url. This will include the headers in the webhook payload at the "request-headers" key as follows:
{
"request-headers": {
"header-name": "header-value"
},
"rest-of-payload":{
...
}
}includeHeaders only works when the request body is a plain JSON object
({}). If the body is a JSON array ([]) or any other type, the headers
will not be merged into the payload.
If you are sending the headers in the webhook payload and you are sending your Data API Key as the Authorization header, the Data API Key will be included in the payload. If you do not want this to happen, you can use the "apiKey" query parameter to specify the Data API Key instead of the Authorization header.
Webhook Authentication
Webhooks can be authenticated using a Data API Key. The Data API Key can be sent to OttoFMS in three ways:
- In the Authentication header as a Bearer token
Authorization: Bearer <data-api-key>- In the "apiKey" query parameter
https://<server>/my/webhook/path?apiKey=<data-api-key>- As a path parameter (OttoFMS 4.10.0 or later)
https://<server>/my/webhook/path/<data-api-key>All of these methods are equivalent and will authenticate the webhook request using the same Data API Key. They are all exposed to give you flexibility in how you configure your webhook and integrate with third party services.
Was this page helpful?