Webhook

Send the event’s data to a URL of your own system as an HTTP POST.

Webhook sends the data of the event to a URL as an HTTP POST with a JSON body. It connects your workflow to anything else: an ERP, CRM, WMS, billing system, dashboard or chat channel.

Webhook is available for every event, and it’s the only automation type for On Start Trip, On Finish Trip, On Geofence Entry, On Geofence Leave, On Routing Finished and On Routing Dispatched.

Required permission:

• View automation
• Create automation

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.

The request is always a POST; there is no method to choose.

Common headers:

Header	Value	Purpose
Authorization	Bearer your-api-token	Authentication
Content-Type	application/json	The body is JSON
X-API-Key	your-api-key	Key-based authentication
X-Custom-Header	custom-value	Anything your endpoint needs

Default body

Without a custom body, the request body is the record that started the automation.

Task events (On Task Created, On Task Assigned, On Task Finished): the task with all its fields.

{
  "_id": "task_id_here",
  "flow": "Delivery",
  "flowId": "flow_id_here",
  "status": "DONE",
  "hubId": "hub_id_here",
  "assignee": ["[e-mail]"],
  "startTime": "2024-01-20T10:00:00.000Z",
  "endTime": "2024-01-20T18:00:00.000Z",
  "createdBy": "[e-mail]",
  "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"
}

On Data Source Created: the record with all its fields.

{
  "_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": "[e-mail]"
}

Routing events (On Routing Finished, On Routing Dispatched): the routing result.

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

Trip and geofence events: see On Start Trip, On Finish Trip and On Geofence Entry.

Custom JSON body

Tick Custom JSON body to send your own JSON instead, with values from the event filled in.

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: ....

Example:

Custom JSON body	Sample payload	Preview
{ "orderId": "{{_id}}", "customer": "{{customerName}}", "status": "{{status}}" }	{ "_id": "6ac4f1a83adc7bd9160645a1", "status": "DONE", "customerName": "Budi Santoso" }	{ "orderId": "6ac4f1a83adc7bd9160645a1", "customer": "Budi Santoso", "status": "DONE" }

Untick Custom JSON body to go back to the default body.

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

Scenario	Event	URL	Headers / rules
ERP sync	On Task Finished (Delivery)	https://erp.example.com/api/deliveries/complete	Authorization: Bearer ..., Content-Type: application/json
Chat alert for urgent tasks	On Task Created (Urgent Delivery)	your chat app’s incoming-webhook URL	Rule: Priority = High
Live dashboard	On Routing Dispatched	https://dashboard.example.com/api/routes/update	X-API-Key: ...
CRM contacts	On Data Source Created (Customer)	https://api.crm.example.com/contacts/create	Authorization: Bearer ...
Invoicing	On Task Finished (Delivery)	https://billing.example.com/api/invoices	X-Billing-Key: ...

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

Nothing is sent.

• 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.

Your endpoint returns an error. Open the run in the log to see the request and the response; check the authentication header and the body your endpoint expects.

The request times out. Your endpoint takes too long. Answer with 200 at once and process the data afterwards; check that the endpoint is up.

You receive duplicates. Look for several automations on the same event, speed up your endpoint so it isn’t retried, and use the _id to ignore repeats.

Questions

Which HTTP method is used? Always POST, with a JSON body.

Are failed webhooks retried? Failed runs stay in the log, where you can retry one or repush several at once. Delivery is not guaranteed while your endpoint is down.

Can I use HTTP instead of HTTPS? It works, but it’s strongly discouraged.