WorkRoad

Registers an https URL to receive the events you list. The response carries the signing secret, and no other response does: store it now. Webhooks belong to the user, not the key, so they fire for jobs started anywhere, including the app.

Required scopes: webhooks:manage

Authorization

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

url*string

An https URL on a public host, up to 2048 characters, with no username or password. localhost, .local, .internal and private IP addresses are refused.

Length1 <= length <= 2048

events*array<>

The events to send. Duplicates are ignored.

Items1 <= items <= 4

Response Body

`application/json`

curl -X POST "https://example.com/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "string",    "events": [      "job.succeeded"    ]  }'

{  "data": {    "id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b",    "url": "https://hooks.example.com/workroad",    "events": [      "job.succeeded",      "job.failed"    ],    "createdAt": "2026-01-15T09:30:00.000Z",    "status": "active",    "failingSince": null,    "disabledAt": null,    "lastDeliveryAt": null,    "lastStatus": null,    "secret": "0000000000000000000000000000000000000000000000000000000000000000"  }}

Create a webhook

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

405application/json

409application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`