Webhook Endpoints
Manage webhook subscriptions and delivery history through the public API.
Webhook management endpoints are available under /public/v1.
Use these endpoints when your integration needs to subscribe, rotate, disable, or inspect webhook delivery behavior programmatically.
Endpoints
GET /webhook-subscriptionsPOST /webhook-subscriptionsDELETE /webhook-subscriptions/:subscriptionIdGET /webhook-deliveries
Call these endpoints from a backend service. Do not expose API tokens or webhook management calls in browser code.
Create a Subscription
curl "$AGILED_API_BASE_URL/public/v1/webhook-subscriptions" \
-X POST \
-H "Authorization: Bearer $AGILED_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-subscription-1" \
-d '{
"target_url": "https://example.com/agiled/webhooks",
"description": "External CRM sync",
"events": ["contact.created", "contact.updated"]
}'Review Deliveries
Use GET /webhook-deliveries to inspect recent delivery attempts. The settings
page shows the latest 50 deliveries.
Review deliveries after creating or changing a subscription. Compare the delivery event, target URL, status, attempts, and response details with your receiver logs.
Manage Subscription Changes
Create one subscription per receiver URL and event set. When changing target URLs or event coverage, create the new subscription, confirm deliveries arrive, then remove the old subscription.
Use stable idempotency keys for automation so a retry does not create duplicate subscriptions.
Rotation Workflow
When rotating a receiver URL or webhook secret, run both old and new receivers briefly if your system allows it. Create the new subscription, send a low-risk event, confirm signature verification and processing, then delete the old subscription.
Keep the old receiver logs available until you are sure no expected events were missed during the change.
Delivery Review Routine
Review deliveries after every subscription change and during incident response. Check status, attempt count, response code, target URL, and event type. Match the Agiled delivery ID with your receiver logs before assuming the event was missing.
If failures repeat, pause downstream processing and fix the receiver before adding more subscriptions.