Agiled Docs

Webhooks notify another system when selected events happen in Agiled.

Create subscriptions only for systems that are ready to receive and verify Agiled webhook requests.

Use one subscription per receiving system or workflow. Separate subscriptions make rotation, troubleshooting, and deletion safer.

Do not point a production webhook at an untested endpoint. The receiving system should be able to verify signatures, respond quickly, store delivery IDs, and process duplicate deliveries safely.

Create A Subscription

Open Settings.
Go to API.
In Webhooks, enter the target URL.
Add a description so teammates know what the webhook is for.
Select one or more events.
Select Create subscription.
Copy the webhook secret immediately.

The secret is used by the receiving system to verify that requests came from Agiled.

Store the secret securely when it is shown. If it is lost, create a new subscription and rotate the receiver configuration.

Treat webhook secrets like passwords. Do not paste them into frontend code, public issue trackers, chat messages, or docs screenshots.

Choose Events

Select only the events the external system needs. A smaller event list is easier to monitor and reduces unnecessary traffic.

Start with one or two low-risk events during testing. Add broader event coverage after your receiver verifies signatures, handles retries, and logs delivery IDs.

Before using production events, the receiver should verify signatures, respond quickly, store event or delivery IDs, and process duplicate deliveries safely. Do not depend on webhooks for business-critical work until these checks pass.

Start In A Test Environment

When possible, point the first subscription at a test or staging receiver. Use a low-risk event and inspect the raw payload, signature verification, response status, and receiver logs before sending production traffic.

If the receiver will create records, send messages, or trigger billing in another system, keep the subscription limited until the downstream side proves it can reject duplicates and recover from failed processing.

Delete A Subscription

Delete a webhook subscription when the external system is removed, the endpoint changes, or the integration should stop receiving events.

When changing endpoints, create and test the new subscription before deleting the old one so event delivery is not interrupted.

Rotate Secrets

If a secret may have been exposed, create a replacement subscription or rotate the receiver configuration, test the new secret, then remove the old subscription.

Test A Subscription

After creating a subscription:

Trigger one low-risk event.
Confirm the receiver returns a successful status.
Verify the signature in the receiver logs.
Store the delivery ID for idempotency.
Confirm the external system processed the event once.
Review Agiled delivery history for the same event.

Review Delivery History

Use webhook delivery history to confirm whether events were sent successfully and to troubleshoot endpoint failures.

Compare Agiled delivery history with receiver logs. Check status code, response body, event name, target URL, and delivery time.

If deliveries fail repeatedly, pause or delete the subscription until the receiver is fixed. Repeated retries against a broken endpoint can create noisy logs and duplicate processing after recovery.

Production Checklist

Before using production webhooks:

Verify signatures in the receiver.
Store delivery IDs for idempotency.
Log event name, status, and processing result.
Return a fast success response only after the event is accepted.
Test duplicate delivery handling.
Document who owns the endpoint and secret.

Create Webhook Subscriptions