Webhooks in Antly provide a powerful way to automate workflows and integrate with external systems by allowing users to subscribe to certain events. When these events are triggered, a payload containing the event details is sent to a specified endpoint. This section explains how to subscribe to webhooks, handle events, and configure endpoints to receive webhook payloads.

1. Subscribing to Webhooks

Purpose:

• To receive real-time notifications when specific events occur in the Antly system, allowing for automation and integration with external systems.

Steps to Subscribe to Webhooks:

Step 1: Create a New Webhook Subscription

• To subscribe to a webhook, you need to send a JQL query to the system.Webhook namespace with the appropriate details about the event and the endpoint where the payload should be sent.

Example JQL Query for Subscribing to a Webhook:

{
    "__meta__": {
        "namespace": "system.Webhook",
        "schema": "controller",
        "intent": "subscribeToWebhook",
        "authenticationClass": "oauth2",
        "authenticationToken": "your_oauth2_access_token"
    },
    "prefix": "YourAppPrefix",
    "trigger": "profile.Customer:create",
    "webhookUrl": "https://yourapp.com/webhooks/handle"
}

• prefix: A unique prefix to identify the webhook subscription, such as the name of your application.
• trigger: The event you want to subscribe to, such as profile.Customer:create, which triggers when a new customer is created.
• webhookUrl: The endpoint URL where the webhook payload will be sent when the event is triggered.

Step 2: Save the Webhook Subscription

• Once you send the subscription query, the system will register your webhook, and Antly will begin sending payloads to your specified endpoint whenever the event occurs.

2. Unsubscribing from Webhooks

If you need to unsubscribe from a webhook, you can send a JQL query to remove the subscription.

Example JQL Query for Unsubscribing from a Webhook:

{
    "__meta__": {
        "namespace": "system.Webhook",
        "schema": "controller",
        "intent": "unsubscribeFromWebhook",
        "authenticationClass": "oauth2",
        "authenticationToken": "your_oauth2_access_token"
    },
    "prefix": "YourAppPrefix",
    "trigger": "profile.Customer:create",
    "webhookUrl": "https://yourapp.com/webhooks/handle"
}

• This query will unsubscribe the specified webhook, stopping Antly from sending further payloads to your endpoint.

3. Handling Webhook Payloads

When an event that you’ve subscribed to is triggered, Antly will send a POST request to the specified endpoint with a JSON payload. This payload contains information about the event, including details about the resource that was created, updated, or deleted.

Example Webhook Payload:

{
    "event": "profile.Customer:create",
    "timestamp": "2024-08-21T10:15:00Z",
    "data": {
        "id": "12345",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "created_at": "2024-08-21T10:00:00Z"
    }
}

Key Components of the Payload:

• event: The name of the event that triggered the webhook (e.g., profile.Customer:create).
• timestamp: The date and time when the event occurred.
• data: The details of the resource affected by the event, such as the ID, name, email, and other relevant fields.

Handling the Payload:

• Your endpoint should be set up to receive and process the incoming webhook payload. Typically, this involves parsing the JSON, validating the data, and performing the necessary actions, such as updating your system, sending notifications, or triggering additional workflows.

4. Securing Webhooks

Security Considerations:

• Use HTTPS: Ensure that your webhook endpoint is accessible over HTTPS to encrypt data in transit.
• Authenticate Webhook Requests: Implement authentication on your endpoint to verify that requests are legitimate. This could be a shared secret, an API key, or a token that is included in the webhook request headers.
• Rate Limit and Throttle: Protect your endpoint from being overwhelmed by implementing rate limiting and throttling mechanisms.