Manage Webhooks

The API Control Plane offers two integration patterns: the Management API (pull-based) and webhooks (push-based). Webhooks send HTTP notifications to your endpoints when events occur — such as new subscriptions, approval requests, API deployments, or configuration changes. This lets external systems react to Control Plane events in real time without polling.

Use webhooks when the Control Plane is the initiator (e.g., notifying a Slack channel about new subscriptions). Use the Management API when your system is the initiator (e.g., deploying APIs from a CI/CD pipeline). Both patterns can be combined for complete bidirectional integration.

List webhooks

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks?page=1&size=10" \
  -H "Authorization: Bearer <your-token>"

Create a webhook

curl -X POST "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Deployment Notifier",
    "url": "https://hooks.example.com/api-events",
    "active": true,
    "eventTypes": ["API_DEPLOYED", "API_UNDEPLOYED"]
  }'

Required fields

Field	Type	Description
displayName	string	Human-readable name
url	string	Endpoint URL to receive webhook payloads
active	boolean	Whether the webhook is active
eventTypes	string[]	Event types that trigger this webhook

Get a webhook

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/<webhook-id>" \
  -H "Authorization: Bearer <your-token>"

Update a webhook

curl -X PUT "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/<webhook-id>" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deployment-notifier",
    "displayName": "Deployment Notifier",
    "url": "https://hooks.example.com/api-events-v2",
    "events": ["API_DEPLOYED", "API_UNDEPLOYED", "SUBSCRIPTION_CREATED"]
  }'

Delete a webhook

curl -X DELETE "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/<webhook-id>" \
  -H "Authorization: Bearer <your-token>"

View webhook delivery history

List past webhook delivery attempts:

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/<webhook-id>/requests?page=1&size=10" \
  -H "Authorization: Bearer <your-token>"

Each delivery record includes the request payload, response status, and any error details.

Get a specific delivery

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/<webhook-id>/requests/<request-id>" \
  -H "Authorization: Bearer <your-token>"

Test a webhook

Trigger a test delivery to verify your webhook endpoint:

curl -X POST "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/<webhook-id>/test" \
  -H "Authorization: Bearer <your-token>"

Retry a failed delivery

curl -X POST "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/requests/<request-id>/retry" \
  -H "Authorization: Bearer <your-token>"

Cancel a pending delivery

curl -X POST "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/requests/<request-id>/cancel" \
  -H "Authorization: Bearer <your-token>"

Delivery statuses

Status	Description
CREATED	Delivery queued
SUCCESS	Successfully delivered
RETRYING	Delivery failed, retrying
GIVE_UP	All retry attempts exhausted
CANCELLED	Delivery cancelled

List all webhook requests

List delivery history across all webhooks:

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/requests?page=1&size=10" \
  -H "Authorization: Bearer <your-token>"

Filter by status:

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/webhooks/requests?status=RETRYING" \
  -H "Authorization: Bearer <your-token>"