Authenticating Webhooks

This feature ensures secure communication between Agency Handy and external systems. By setting up authentication, you can protect data transmission and ensure that only authorized endpoints receive webhook data.

Benefits

• Security: Protect sensitive data from unauthorized access.

• Reliability: Ensure that webhook data is only sent to and received by authorized endpoints.

• Compliance: Meet security and compliance requirements for data transmission.

Steps to Use

To Set Up Webhook verification

We highly recommend verifying the webhooks that you receive in your endpoint. You can verify the webhook in the following way:

Verify Webhook

POST /api/v1/webhooks/verify-signature

Headers (required)

Name	Value
Content-Type	application/json

Body(required)

Name	Type	Description
webhookId	string	Webhook Id
signature	string	signature of the webhook
secret	string	webhook secret
payload	object	webhook payload

You can find webhookId after you have created a webhook.

You can get the webhook signature from the request header named.

x-ah-sig

You can get the webhook secret after you have created a webhook. You can find the payload in the request body on the sidebar webhook secret.

Response

200

{
    "verification_status": "SUCCESS"
}

403

{
    "type": "PermissionError",
    "status": 403,
    "verification_status": "FAILED"
}

Example:

JavaScript

const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';
const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',
  secret: 'your_webhook_secret',
  payload: {}, // Your payload object here
};

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(postData),
  });

  const data = await response.json();
  console.log('Success:', data);
} catch (error) {
  console.error('Error:', error);
}

cURL

curl -X POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature \
     -H "Content-Type: application/json" \
     -d '{
           "webhookId": "your_webhook_id",
           "signature": "your_signature",
           "secret": "your_webhook_secret",
           "payload": {}
         }'

Important Notes

• Token Management: Keep the token secure and change it periodically to maintain security.

• Endpoint Security: Ensure the endpoint URL is secure and can validate the token.

• Regular Monitoring: Monitor the webhook activity to detect any unauthorized access attempts.

• Documentation: Maintain a record of the authentication tokens and their corresponding endpoints for reference and troubleshooting.