What are Webhooks?
Webhooks allow you to collect data about events as they happen in near real-time.
Provide an HTTP or FTP endpoint, select for which KanbanBOX events you want that endpoint to receive data, and KanbanBOX will send it to you as the events take place.
Communication protocols
KanbanBOX can send data over the following protocols:
- HTTP / HTTPS
- FTP / FTPS
- SFTP
Data format
Webhook data can be sent as:
- JSON
- CSV (separators, end line characters and quotes can be configured)
- XML
- TXT
Endpoint availability
If the destination server can’t be reached, or data transfer is not successful, KanbanBOX will temporarily stop the webhook and try again after 2 minutes. Meanwhile, any other call for the same webhook will be added to the webhook queue and stay on hold.
If the communication is not successful again, KanbanBOX will wait every time longer and retry, as described here:
| Attempt nr. | Timing | Notification |
|---|---|---|
| 1 | Real time when webhook is triggered. | |
| 2 | At least 2 minutes after previous attempt. | |
| 3 | At least 5 minutes after previous attempt. | Email notification on fail. |
| 4 | At least 10 minutes after previous attempt. | |
| 5 | At least 20 minutes after previous attempt. | Email notification on fail. |
| 6 | At least 20 minutes after previous attempt. | |
| 7 | At least 40 minutes after previous attempt. | Email notification on fail. |
| 8, 9 and on | At least 60 minutes after previous attempt. |
Email notifications on failed attempts are sent to the email addresses as specified in the webhook configuration.
Once communication works again, the whole queue of calls will be processed, following the FIFO order of messages, without risks for data losses. An email notification on successfull attempt is sent to the email addresses specified in the webhook configuration.
If after 7 days from the initial trigger time the communication is still not successful, KanbanBOX gives up trying and move on to the next message waiting in queue that is less than 7 days old.
Authentication
When creating a webhook, different types of authentication to the external system are available.
- No Auth: This is usually paired with the addition of an HTTP Header. For example:
-
Authorization: Bearer {token}, or X-API-KEY: {api_key}- Basic Auth
- OAuth 2.0 Client Credentials
- OAuth 2.0 Password Credentials
It is possible to discuss different requirements for authentication with the KanbanBOX team, during the integration project.
Webhook over HTTP
Testing HTTP webhooks
To test KanbanBOX webhooks before setting up your scripts, we recommend using a system that generates endpoint, collects requests and allows to inspect them in a human-friendly way.
We have deployed a version of RequestBin, ready to use for you at https://requestbin.kanbanbox.com.
Click on the “Create a RequestBin” button, and copy/paste the Bin URL in the webhook url field.
The Bin URL will be in the form: https://requestbin.kanbanbox.com/{unique_bin_id}
Webhooks can be inspected at: https://requestbin.kanbanbox.com/{unique_bin_id}?inspect
HTTP webhooks common data
HTTP method: POST
Useragent: KanbanBOX
HTTP webhooks identifier
Each webhook will have an identifier header with a unique value for each call:
"Request-Id" : {request_id_value},
HTTP webhooks calls timeout
Once set up, webhooks are triggered in near real time every time the selected event occurs.
KanbanBOX will make a HTTP call to the provided url, and will wait for an answer for 30 seconds.
If KanbanBOX is receiving no answer, or if the answer HTTP response code is different than “200 OK”, KanbanBOX will stop the webhook and will try again later.
HTTP webhooks signature
Each webhook call is signed as follows:
$signature = base64_encode(hash_hmac('sha1', $signed_data, $webhook_key, true));
Where:
-
$signed_data: string concatenation of request full url (with protocol) and each sorted key/value in the kanbanbox_params array of request body (values that are arrays themselves are skipped in the concatenation); -
$webhook_key: key value as inserted in the webhook form of KanbanBOX; -
true: makes the hash_hmac function output raw binary data.
The signature is added as the HTTP Header parameter X-kanbanbox-signature.
Signature is useful to make sure that the message arriving to your web service was really sent from KanbanBOX.
Following is an example of signature calculation using PHP:
function _signature($webhook_key, $url, $params_array)
{
$signed_data = $url;
ksort($params_array);
foreach ($params_array as $key => $value) {
$signed_data .= $key;
if ( ! is_array($value)) {
$signed_data .= $value;
}
}
$signature = base64_encode(hash_hmac('sha1', $signed_data, $webhook_key ?? '', true));
return $signature;
}
Webhooks over FTP or FTPS
When sending data over FTP, you can choose if appending data always to the same file, or create a new file for each data exchange. In both cases, file name can be configured.
Webhooks over SFTP
When sending data over SFTP, data appending to an existing file is not supported. A new file will be created for each data exchange.
User interface
You can set the parameters and contents of the webhooks in a user friendly interface. You can choose a parameter or a field from a list and enter its value. For some fields, there is an explanation of its meaning, like in the pictures below.
“Set kanban” webhooks
“Set kanban” webhooks can be triggered by these events:
- A kanban card is set empty
- A kanban card is set released
- A kanban card is set in process
- A kanban card is set done
- A kanban card is set in transit
- A kanban card is set full
- A kanban card is consumed
| Field | Description |
|---|---|
| HTTP Method | POST |
| HTTP Header | Content-Type: application/json Content-Length: X-kanbanbox-signature: |
| Event data | A json array containing the following data:
{
} |
In case of “set released” of a batch of kanban cards, KanbanBOX will send out one “set released” webhook for each kanban card.
Customizing webhook data transmission
Optionally, it is possible to modify some parameters of the transmission protocol, by adding a configuration in the “Protocol parameters” field of the KanbanBOX webhook form.
Following are the details of all available parameters:
| Parameter | Available when | Description |
|---|---|---|
| content_type | HTTP, HTTPS | Custom content type value in the header. When present, this setting overwrites the default content type that is set according to the data format. Example: “content_type”:“text\/xml” |
| additional_http_headers | HTTP, HTTPS | Array of strings. Each string will be added as an additional header in the HTTP call.
Example: “additional_http_headers”: [
] |
| xml_template_string | XML | When specified and the data format is XML, the body of the HTTP call will contain the template string, with all variables {variable_name} replaced by corresponding values. Variables must be defined in the webhook content configuration.
Example: “xml_template_string”: < xml>
<\ /xml>” |
| filename | FTP, FTPS, SFTP | Filename to use for data transmission. The filename can contain all the variables specified in the content configuration as {variable_name}, plus {microtime}, that contains the timestamp in microseconds to ensure uniqueness.
Example: "filename":"{microtime}_{part}-order.csv" N.B.: Hidden fields in filename can be added, if they are added in the content, specifying "type": "hidden". |
| file_appending | CSV and XML over FTP, FTPS | Appends data to the file if exists, instead of generating every time a new file. Filename configuration must be coherent with this setting (if filename has variables that makes it every time different, data will never be appended). When file_appending = 1, then use_ftp_wrapper must be 0. Accepted values: 1 (enabled) or 0 (disabled) Default: 0 |
| csv_headers | CSV | Whether first line should contain field names or not. Accepted values: 1 (yes) or 0 (no) Default value: 1 |
| csv_quotation_marks | CSV | Whether values will be wrapped into quotation marks or not. Default value: double quote ( " )
Example: "csv_quotation_marks":"\"" (double quotes) "csv_quotation_marks":"\"" (single quotes) "csv_quotation_marks":"" (no quotes) |
| csv_separator | CSV | Character or characters sequence to use as separator between values. Default value: semicolon ( ; ) Example: "csv_separator":"," (comma) "csv_separator":"\t" (tab) |
| csv_end_of_line_json | CSV | End of line characters. Default value: Windows style ( \r\n ) Example: "csv_end_of_line_json":"\r\n" (Windows style "csv_end_of_line_json":"\n" (Unix style) |
| use_ftp_wrapper | FTP, FTPS | Some server configurations have problems when the default FTP wrapper is used. In these cases, try to disable it. The FTP wrapper must be disabled when file_appending = 1 Accepted values: 1 (enabled) or 0 (disabled) Default value: 1 |
| Xml_node | XML | Nodes must be defined in the webhook content configuration.
Example: { "xml_node": "row", "xml_basenode": "order", "file_appending":0 } |
Customizing webhook content
It is possible to customize the content and format of data sent by a webhook, by adding a configuration in the “Content” field of the KanbanBOX webhook form.
Variable values
For each content part, you can define:
- field: KanbanBOX field
- name: custom field label
- date_format: custom format applied to date values, following PHP convention as explained at http://php.net/manual/en/function.date.php
Constant values
You can also specify additional constant values using the following format:
- field: “constant”
- name: custom field label
- value: the requested constant string
In the value field of a “constant” value, you can also combine fixed strings, other variables from the webhook content as well as
the special functions variable as they are available in the template editor
(read the guide about Special variables).
For example:
Hidden fields
Hidden fields can be added to the dataset, specifying type = hidden.
A hidden field is useful when you need to use the field value in the file name (for FTP webhooks), but you don’t need it in the message body.
Examples
Following is an example of webhook body content in json format:
{
"kanbanbox_params":
{
"Part_Number":"VIT0027",
"Supplier_ID":"S001",
"Quantity":"33",
"Unit_of_Measure":"PZ",
"Required_Date":"12\/05\/2018",
"Ekanban_String":"X7QQWDPG",
"Plant":"main"
}
}
The same webhook, when configured as CSV, would generate a file like this:
"Part_Number","Supplier_ID","Quantity","Unit_of_Measure","Required_Date","Ekanban_String","Plant"
"VIT0027","S001","33","PZ","12/05/2018","X7QQWDPG",”main”
Webhook execution
The execution of the webhook can be immediate or scheduled.
Immediate webhook
When the execution is set as "Immediate" and the trigger event occurs, the message is immediately sent to the endpoint.
Scheduled webhook
When the execution is set as "Scheduled" and the trigger event takes place, the message is saved in a queue. All the messages in the queue are sent to the endpoint at the moment defined in the "Schedule Expression".
The "Schedule Expression" is written following the AWS cron expressions.
With a scheduled webhook it is possible to:
- generate a single order with multiple lines (1 PO line corresponds to 1 card),
- group cards to consolidate quantities in one order (1 PO line corresponds to multiple cards).
With the option Group by fields, you can send different messages, grouping the ones with the same value in the selected field.
For example, if the field selected is supplier_name, KanbanBOX will generate a message for each supplier that is in a message in the queue.
The Group by fields allows you to select multiple fields.
With the option Combine rows content you can consolidate cards to generate 1 order that corresponds to multiple cards.
When a webhook is scheduled, in the Webhooks table, under the Operations column, there are two more options:
- Events awaiting scheduled execution, with all the messages in the queue, waiting for the schedule to be sent;
- Launch scheduled execution now, to manually send the messages in the queue to the endpoint.
SOAP-like webhooks
Even if SOAP is not officially supported as a transmission protocol, KanbanBOX can send SOAP-like messages, as SOAP messages can be sent as HTTP POST messages with special headers and body.
You can use tools like SOAP UI (https://www.soapui.org) to test your SOAP interface and extract the HTTP headers and body of SOAP messages; then create a HTTP/S webhook and specify the protocol parameters additional_http_headers, content_type and xml_template_string accordingly.
Here is an example, for a message sent to the SOAP interface of Microsoft Dynamics AX:
{
"content_type":"text\/xml;charset=UTF-8",
"additional_http_headers":[
"SOAPAction: http:\/\/schemas.microsoft.com\/…\/KanbanBOXService\/process"
],
"xml_template_string": "<soapenv:Envelope
xmlns:soapenv=\"http:\/\/schemas.xmlsoap.org\/soap\/envelope\/\"
xmlns:dat=\"http:\/\/schemas.microsoft.com\/dynamics\/…\/datacontracts\"
xmlns:arr=\"http:\/\/schemas.microsoft.com\/…\/Arrays\"
xmlns:rout=\"http:\/\/schemas.microsoft.com\/…\/routing\"
xmlns:dyn=\"http:\/\/schemas.datacontract.org\/…\/Dynamics.Ax.Application\">
<soapenv:Header>
<dat:CallContext>
<dat:Company>aaa<\/dat:Company>
<dat:Language><\/dat:Language>
<\/dat:CallContext>
<\/soapenv:Header>
<soapenv:Body>
<rout: KanbanBOXServiceProcessDataRequest>
<rout:_dataContract>
<dyn:ConfirmedDate>{ConfirmedDate}<\/dyn:ConfirmedDate>
<dyn:ItemId>{ItemId}<\/dyn:ItemId>
<dyn:KanbanId>{KanbanId}<\/dyn:KanbanId>
<dyn:Qty>{Qty}<\/dyn:Qty>
<dyn:ReleasedDate>{ReleasedDate}<\/dyn:ReleasedDate>
<dyn:VendAccount>{VendAccount}<\/dyn:VendAccount>
<dyn:WMSLocation>{WMSLocation}<\/dyn:WMSLocation>
<\/rout:_dataContract>
<\/rout:DLX_ KanbanBOXServiceProcessDataRequest >
<\/soapenv:Body>
<\/soapenv:Envelope>"
}
Commenti
0 commenti
Accedi per aggiungere un commento.