Webhook Integration Guide for External Developers

Introduction

Welcome to the Agile.Now Webhook Integration Guide. This document provides critical information for external developers about setting up and utilizing webhooks with Agile.Now, thereby enabling real-time data synchronization and enhancing automation across various applications.

Understanding Agile.Now Webhooks

Agile.Now webhooks are specifically designed to provide immediate notifications to your applications upon the occurrence of specified events within the Agile.Now system. Leveraging webhooks facilitates the automation of workflows, synchronizes data in real-time, and contributes to the creation of more interactive applications.

Available Events

Webhooks in Agile.Now can be activated by a wide range of events pertaining to entities and Agile.Now workflows, including but not limited to:

• Entity Created/Updated/Deleted: Receive notifications when any entity is created, updated, or deleted.
• Discover all supported entities: Use the /Endpoint/rest/api/v1/Entities endpoint to see all entities that can trigger webhooks.

Setting Up Webhooks

Follow these steps to set up a webhook with Agile.Now:

1. Log into your Agile.Now account and navigate to the "Settings" section.
2. Select "Webhooks" and then click on "Add Webhook Connection".
3. Configure your webhook by specifying the necessary details:
   • URL Endpoint: The server endpoint URL that will receive the webhook payloads.
   • Entities: Choose the entities that, when modified, will trigger the webhook.
   • Events: Select specific events that will activate the webhook.
   • Secret (optional): A secret key for signing payloads to enhance security.

Security and Validation

Agile.Now emphasizes security through the following measures:

• HTTPS: Ensures that all webhook endpoints are served over HTTPS.
• Payload Signature: Every payload is signed with the provided secret, allowing the recipient to verify the payload's integrity and authenticity.

Verifying Signatures

Verify a webhook payload signature by:

1. Computing the HMAC SHA256 hash of the payload using the secret key.
2. Comparing your hash against the X-Signature header in the incoming request.

Handling Webhook Payloads

Below is a table detailing the event payload structure parameters:

Payload Structure for Individual Entity Update

For an update event related to an individual entity like Department, the webhook payload is structured in JSON with specific fields:

{
   "TenantId": "B78C8D86-5EFE-4460-879B-F78933E00262",
   "EventType": "Updated",
   "EventId": "BB5BA04A-99B3-4286-97B8-191922CE5E15",
   "Version": "1.0.0",
   "Timestamp": "2024-04-11T13:10:41Z",
   "EventRecord": "Department",
   "EventResponse": "Object",
   "Data": {
      "Id": "B78C8D86-5EFE-4460-879B-F78933E76262",
      "ExternalId": "0987654321",
      "Name": "Department-0987654321",
      .....
   }
}

Payload Structure for Bulk Entity Update

For bulk update events affecting entities like Department, the payload includes an array of entities under Data:

{
   "TenantId": "B78C8D86-5EFE-4460-879B-F78933E00262",
   "EventType": "Updated",
   "EventId": "BB5BA04A-99B3-4286-97B8-191922CE5E15",
   "Version": "1.0.0",
   "Timestamp": "2024-04-11T13:10:41Z",
   "EventRecord": "Department",
   "EventResponse": "Array",
   "Data": [
      {
         "Id": "B78C8D86-5EFE-4460-879B-F78933E76262",
         "ExternalId": "0987654321",
         "Name": "Department-0987654321",
         .....
      },
      {
         "Id": "D98C8D86-4EFE-4460-879B-F78933E76263",
         "ExternalId": "1234567890",
         "Name": "Department-1234567890",
         .....
      }
   ]
}

Header and query string parameters

Below is a table and usage example detailing the event payload structure parameters, focusing on the security aspects of using a signature and API key in webhook implementations:

Usage Example

• Signature in HTTP Header: When a webhook is sent, the X-Signature HTTP header contains a cryptographic hash. The receiving server uses this hash, along with a shared secret, to verify that the payload hasn't been altered.

POST /webhook?ApiKey=yourApiKeyHere HTTP/1.1
Host: example.com
X-Signature: abc123def456ghi789...
Content-Type: application/json

{ "EventType": "Update", "Data": { ... } }

• API Key in Query String: The ApiKey query parameter is appended to the webhook URL. This key enables the receiving server to authenticate the request as originating from a known and trusted source.

Considerations

• Security of the API Key: While the API key provides a layer of authentication, transmitting it via the query string can potentially expose it through server logs or browser history. It is imperative to use HTTPS for all communications to encrypt the query parameters and protect them from interception.
• Signature Verification: The signature should be verified on the server side using the shared secret. This verification process is crucial for ensuring that the webhook was genuinely sent by the expected sender and that the payload remains unchanged during transmission, maintaining both the integrity and authenticity of the data.

Best Practices

• Acknowledge Receipt: Respond promptly to webhook payloads with a 200 OK status to confirm receipt.
• Idempotent Processing: Design your application to handle duplicate webhook calls safely.

Troubleshooting

• Logs and History: Agile.Now maintains a log of webhook activities to aid in debugging failed deliveries.
• Retry Mechanism: In the event of delivery failures, Agile.Now attempts retries according to an exponential backoff strategy, up to 3 times.

Conclusion

Webhooks in Agile.Now are a potent tool for integrating real-time event notifications into your applications, significantly enhancing automation and workflow efficiency. By adhering to this guide, external developers can