Create a webhook (secret returned once)
Registers an HTTPS URL for the events you list and returns the webhook with its whsec_ signing secret, the only time that secret is returned. Each delivery is a signed POST of {id, type, created_at, data}. Listing a batch event needs batch read access and a balance event billing read access, beside webhook write access (403 otherwise). A name the platform sends no event for is stored and never delivered.
Required permission
Requires the webhook.write permission. See Permissions for the roles and API key permissions that include it.
Command line
The orl CLI wraps this endpoint:
orl webhooks create --name <name> --url <url>apiKeyAuthorizationBearer <token>OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).
orgId*stringapplication/json- body
name*stringurl*stringevents?array<>The event types to deliver: vm.running, vm.stopped, vm.terminated, vm.interrupted, batch.completed, batch.failed, batch.expired, batch.cancelled, balance.low and balance.depleted. Empty or absent delivers the four vm events; a batch or balance event reaches only a webhook that lists it. Listing a batch event also needs batch read access, and a balance event billing read access. A name outside this list is stored but never delivered: the server does not reject it, so an existing webhook may carry one from before this list existed. * is not a wildcard; it matches nothing.
Created
application/json- response
id*stringname*stringurl*stringsecretPrefix*stringevents*array<string>The event types this webhook receives. Empty means the four vm events.
enabled*booleancreatedAt*stringsecret*stringcurl -X POST 'https://api.openrelay.inc/v1/orgs/string/webhooks/create' \ -H 'Content-Type: application/json' \ -d '{ "name": "deploy-events", "url": "https://example.com/hooks/openrelay", "events": [ "vm.running", "vm.terminated", "batch.completed" ]}'{ "id": "string", "name": "string", "url": "string", "secretPrefix": "string", "events": [ "string" ], "enabled": true, "createdAt": "string", "secret": "string"}List an org's webhooks (no secrets) GET
Returns every webhook in the org with its URL, subscribed events, enabled flag and secret prefix. The full signing secret is shown only on create or regenerate.
Update a webhook (name/url/events) PATCH
Changes a webhook's name, URL or subscribed events and returns it. A field left out keeps its value; the signing secret and enabled state are not changed. Whatever it changes, an update needs the access the webhook's events need on create, since a new URL would redirect them.