Skip to main content
Routal

Create a webhook

Registers a public endpoint that receives a POST every time one of the enabledevents happens in the project.

POST
/v2/webhook

Registers a public endpoint that receives a POST every time one of the enabled_events happens in the project. The URL must be public: private, loopback and link-local addresses are rejected.

Send a test event with POST /v2/webhook/{id}/test to check that your endpoint answers before relying on it.

Authorization

api_key
private_key<token>

Pass your API key as the private_key query string parameter. Generate and rotate keys in Developer Settings of your Routal workspace.

Keys stay server-side. Never ship them to a browser or mobile app.

In: query

Query Parameters

project_id*string

Project id

Match^[0-9a-f]{24}

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/webhook?project_id=string" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/routal/webhooks",    "enabled_events": [      "routal.planner.2.plan.created",      "routal.drivers.2.route.finished"    ],    "enabled": true  }'
{
  "id": "4f75d991ac359f8c4c79d762",
  "organization_id": "4f75d991ac359f8c4c79d762",
  "project_id": "4f75d991ac359f8c4c79d762",
  "url": "https://example.com",
  "enabled_events": [
    "routal.planner.2.plan.created",
    "routal.drivers.2.route.finished"
  ],
  "enabled": true,
  "failure_count": 0,
  "created_by": "4f75d991ac359f8c4c79d762",
  "created_at": "2026-11-10T16:55:36.096Z",
  "updated_at": "2026-11-10T16:55:36.096Z",
  "deleted_at": "2026-11-10T16:55:36.096Z"
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
Empty