Prerequisites

An active account with access to AGILITY and the necessary credentials and permissions to access the API (login ID and password) from your administrator or Administrator rights in the AGILITY UI.
A valid URL endpoint on your server to receive webhook notifications.

Register a webhook subscription

To start receiving webhook events, create and register a webhook endpoint.

You can register and create one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

Identify which events you want to monitor.
Create a webhook endpoint function to receive event data POST requests.
Register your endpoint within the AGILITY UI using the Webhooks UI or the API.
Secure your webhook endpoint.

1. Identify the events to monitor

Use the AGILITY API reference (accessible under {baseUrl}/cv/api/public/docs) to identify the events and the event objects your webhook endpoint service needs to parse.

2. Create a webhook endpoint function

Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method. We recommend your webhook endpoint function to use HTTPS.

Set up your endpoint function so that it:

Handles POST requests with a JSON payload consisting of an event object
Quickly returns a successful status code (2xx) prior to any complex logic that could cause a timeout

See Verify events are sent from AGILITY for an example.

3. Register and manage your webhooks in AGILITY

To register the webhook endpoint’s accessible URL in AGILITY, use the Webhooks section in the AGILITY UI or use the API. This ensures that AGILITY knows where to deliver events.

Registered webhook endpoints must be publicly accessible HTTPS or HTTP URLs (we strongly recommend HTTPS).

Webhook URL format

The URL format to register a webhook endpoint is:

https://<your-website>/<your-webhook-endpoint>

For example, if your domain is https://mycompanysite.com and the route to your webhook endpoint is @app.route('/agility_webhooks', methods=['POST']), specify https://mycompanysite.com/agility_webhooks as the endpoint URL.

Register a webhook endpoint with the AGILITY API

To programmatically create webhook endpoints, use the AGILITY API.

Follow this example to create an endpoint that notifies you when requested analysis finished.

Send a POST request to /cv/api/v1/webhooks/subscriptions with the following data:

url: The URL of your webhook endpoint.
events: A list of events you want to subscribe to. Available events include analysis_done . Use ["*"] to subscribe to all events.
description (optional): A brief description of your webhook.
enabled (optional): Set to true to enable the webhook immediately.

curl -X 'POST' \
  'https://agility.b-yond.com/cv/api/v1/webhooks/subscriptions' \
  -H 'accept: application/json' \
  -H 'userId: 1234' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "events": [
    "*"
  ],
  "description": "My webhook",
  "enabled": true,
  "subscribe_to_all_users": true
}'

Store your webhook Secret

Upon successful registration, you'll receive a secret in the response. Store this secret securely, as it is used to verify incoming webhook requests

{ "id": "566eafd2-0b9d-4203-9671-7ef66125f568", "user_id": "1234", "url": "Example Domain ", "events": [ "*" ], "description": "My webhook", "enabled": true, "subscribe_to_all_users": true, "secret": "0cb6ce59c1e6d5062c97d7c5c9866288", }

Manage a webhook endpoint configuration

You can update or delete existing webhook endpoints using the AGILITY Webhooks dashboard page.

You also have the option to temporarily disable a registered webhook endpoint.

For programmatic management of webhook endpoints, you can use the API.

4. Secure your webhooks

After confirming that your webhook endpoint connection functions as expected, secure the connection by implementing webhook best practices.

One particularly important best practice is to use webhook signatures. This method helps verify that the webhook request was generated by AGILITY and ensures that it didn’t come from a server attempting to mimic AGILITY.

Handling incoming webhooks

Receive notifications
- Your endpoint will receive POST requests with JSON data for the subscribed events.
Verify signatures (Optional)
- Use the provided secret to verify the signature of incoming webhook requests for added security.

Next: Best practices for webhooks and troubleshooting