Webhooks API

Overview

Outbound webhooks let you receive real-time notifications when events occur on your connection. You create a subscription with a target URL and a list of event types. When a matching event fires, Configly sends a signed POST request to your URL with the event payload.

For the list of events you can subscribe to, see Webhook event types.

Create a subscription

curl -X POST https://api.configly.app/v1/webhooks \
  -H "Authorization: Bearer cly_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["config.applied", "health_check.completed"],
    "description": "Production monitoring"
  }'

The response includes a secret field with a whsec_ prefix. Use this to verify incoming webhook signatures.

Maximum 10 subscriptions per connection. Attempting to exceed this returns 400 LIMIT_EXCEEDED.

List subscriptions

curl https://api.configly.app/v1/webhooks \
  -H "Authorization: Bearer cly_your_key"

Returns a paginated list of subscriptions. Supports page and limit query parameters.

Get a subscription

curl https://api.configly.app/v1/webhooks/{id} \
  -H "Authorization: Bearer cly_your_key"

Returns subscription details. The secret is never included in read responses.

Update a subscription

curl -X PUT https://api.configly.app/v1/webhooks/{id} \
  -H "Authorization: Bearer cly_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["config.applied"], "active": true }'

All fields are optional. Send only the fields you want to change. Setting active to true re-enables a disabled subscription, resets its failure count to zero, and clears any disabled state.

Delete a subscription

curl -X DELETE https://api.configly.app/v1/webhooks/{id} \
  -H "Authorization: Bearer cly_your_key"

Returns 204 No Content with no response body.

Delivery log

curl https://api.configly.app/v1/webhooks/{id}/deliveries \
  -H "Authorization: Bearer cly_your_key"

Returns a paginated list of delivery attempts for a subscription. Each entry includes the event payload, HTTP response status, and any error messages.

Test a subscription

curl -X POST https://api.configly.app/v1/webhooks/{id}/test \
  -H "Authorization: Bearer cly_your_key"

Sends a single test event (connection.sync_completed with test: true in the data) to the subscription URL. Test deliveries are single-shot: if the delivery fails, it is not retried. Disabled subscriptions reject test calls with 400.

Response shapes

Subscription

Delivery

Error codes