Webhooks

The partner API can register, list and delete webhooks. Nothing in Pentr sends a webhook. Registering one stores a URL and a list of event names, and has no other effect.

Registering a webhook¶

curl -X POST https://<pentr-host>/api/v1/webhooks \
  -H "X-API-Key: $PENTR_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/pentr", "events": ["engagement.completed"]}'

{
  "id": "4e9cbcf3-f7e7-44af-abba-8243e5b579eb",
  "url": "https://hooks.example.com/pentr",
  "events": ["engagement.completed"],
  "is_active": true,
  "created_at": "2026-09-23T09:42:31.873602"
}

Both fields are required: url a string and events a list of strings. Neither is validated beyond its type. "not a url" is accepted as a URL, an empty events list is accepted, and so is any string as an event name. The same URL can be registered more than once. url is stored in a column of 500 characters. A value one character over the limit is refused by the database and answered with a plain-text 500. A value over the limit whose excess characters are all spaces is truncated to 500 characters and the request succeeds. There is no signing secret, in the request or the response.

Listing and deleting¶

GET /api/v1/webhooks returns the organization's webhooks whose is_active is true. Every webhook is created with is_active set to true, and nothing sets it to false, so the list holds every webhook registered and not deleted.

DELETE /api/v1/webhooks/{webhook_id} removes the webhook permanently and answers 204. A second delete of the same id, or a delete of another organization's webhook, answers 404:

{"detail": "Webhook not found"}