Webhook

​

Automation detail

1. URL: required. Where the request is sent, for example https://erp.example.com/hooks/delivery. It must be reachable from the internet and accept POST requests. Use HTTPS.
2. Add header: add a header to the request. Without headers, the text “No header. The request is sent as-is.” is shown.
3. Header name, for example Authorization.
4. Header value, for example Bearer your-api-token. The trash icon removes the header.
5. Custom JSON body: tick to replace the default body with your own JSON. See Custom JSON body.

​

Default body

{
  "_id": "task_id_here",
  "flow": "Delivery",
  "flowId": "flow_id_here",
  "status": "DONE",
  "hubId": "hub_id_here",
  "assignee": ["[email protected]"],
  "startTime": "2024-01-20T10:00:00.000Z",
  "endTime": "2024-01-20T18:00:00.000Z",
  "createdBy": "[email protected]",
  "createdTime": "2024-01-20T09:30:00.000Z",
  "organizationId": "org_id_here",
  "customerName": "Budi Santoso",
  "customerAddress": "Jl. Sudirman No. 123, Jakarta",
  "deliveryCoordinate": "-6.2088,106.8456"
}

{
  "_id": "data_id_here",
  "dataType": "Customer",
  "dataTypeId": "datatype_id_here",
  "organizationId": "org_id_here",
  "createdTime": "2024-01-20T09:30:00.000Z",
  "name": "Budi Santoso",
  "email": "[email protected]"
}

{
  "_id": "routing_id_here",
  "name": "Route Plan Name",
  "status": "FINISHED",
  "organizationId": "org_id_here",
  "createdTime": "2024-01-20T09:30:00.000Z",
  "vehicles": ["..."],
  "visits": ["..."]
}

​

Custom JSON body

1. Insert variable: pick a field of the trigger’s task type to insert its placeholder at the cursor.
2. Beautify: format the JSON. If the text isn’t valid JSON yet, “Cannot format — not valid JSON” is shown.
3. Custom JSON body: the body to send. Write a value as {{key}} to have it replaced with the event’s value when the automation runs, for example "customer": "{{customerName}}".
4. Sample payload: paste an example of the default body, for example copied from the log. It’s only used to help you write the body and is not saved.
5. Available keys: the keys found in the sample payload. Click one to insert it at the cursor. Nested keys are written with dots, for example hub.name.
6. Preview: the body as it would be sent for the sample payload. Keys that the sample doesn’t contain are listed as undefined: ....

​

How it works

1. The event happens and the rules, if any, are checked.
2. The body is prepared: the default record, or your custom body with its placeholders filled in.
3. Your headers are added.
4. The POST request is sent to the URL.
5. The request, your endpoint’s status code and its response are recorded in the log, where failed requests can be retried.

​

Examples

​

Security

• Always use HTTPS so the data is encrypted in transit.
• Protect your endpoint with an Authorization header or an API key, and check it on every request.
• Validate the body’s structure on your side.
• Rotate keys regularly and keep them out of shared documents.
• If your firewall allows it, accept requests only from known addresses.

​

Good practice

• Test your endpoint before switching the automation on.
• Answer quickly with a 2xx status and do heavy work in the background.
• Make your endpoint idempotent, using the record’s _id, so a retried or repeated request does no harm.
• Use rules to send only what your system needs.
• One automation sends to one URL. To send to several, create one automation per URL.

​

Troubleshooting

• Check that the automation is Active, its event and task type match, and the rules don’t exclude the record.
• Check that the URL is valid and reachable from the internet.

​

Questions