Subscribe to events

POST/v1/webhooks

Needs a bearer access token with the webhooks.write scope. How authentication works

Registers an HTTPS endpoint to receive the events you choose. The response includes a signing secret. It is shown only once, so store it now. Use it to verify the X-Rolefy-Signature header on every delivery.

curl -X POST "https://developer.rolefy.fit/api/v1/webhooks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "target_url": "https://example.com/webhooks/rolefy",
  "events": [
    "application.created",
    "application.status_changed"
  ]
}'

201 · Subscription created

{
  "data": {
    "id": "3b1f7c52-8e4a-4d1b-9c0e-5a6d2f8b7e41",
    "target_url": "https://example.com/webhooks/rolefy",
    "events": [
      "application.created",
      "application.status_changed"
    ],
    "status": "active",
    "created_at": "2026-03-14T09:30:00Z",
    "secret": "whsec_…"
  }
}

Request bodyapplication/jsonrequired

target_urlstringrequired
A public https:// URL.
eventsarray of stringrequired
Allowed values:application.createdapplication.status_changedjob.status_changed

Responses

201Subscription created
Response fields
- dataobject
  idstring · uuid
  target_urlstring
  eventsarray of string
  Allowed values:application.createdapplication.status_changedjob.status_changed
  statusstring
  Allowed values:activedisabled
  created_atstring · date-time
  secretstring
  Shown only in this response.

400Invalid request (invalid_request)

Example response

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request (`invalid_request`)."
  }
}