Event-driven Webhooks in Addigy provide a powerful way to receive real-time notifications about specific events within your Addigy environment. This enables you to automate responses, integrate with other services, and enhance your management capabilities.
NOTE: Webhooks sent from Addigy require the receiving service to authenticate with a one-time verification challenge sent in the Addigy Webhook POST as part of the header, X-Addigy-Webhook-Validation-Token.
Creating a Webhook
To create a Webhook in Addigy, navigate to Account > Integrations > API & Webhooks.
You’ll need a URL, any necessary headers, and an event trigger. Configure your Webhook to trigger whenever a specific event in Addigy occurs. The Events dashboard shows the event data you can use to build triggers.
- Webhook Name: Name of the Webhook for your reference.
- Action Callback: The URL that you would like Addigy to make a POST to when the event trigger fires.
-
Event Triggers: A combination of Addigy event properties that should trigger the Webhook. For example, if you want to trigger an event when LiveTerminal is enabled or disabled, you would set Receiver Type to "platform" and Receiver Identifier to "liveterminal." This information can be found in the Events tables throughout Addigy.
Verification Challenge - Required
When you create or save changes to a Webhook, Addigy will send a challenge request to the URL with a validation token header, X-Addigy-Webhook-Validation-Token. Your service should respond with the same token and a 200 status to validate (using the same key as a header or in the post body). If the verification passes, your webhook will be saved and ready to go!
Webhook Secret - Recommended
Each saved Webhook includes a secret that is used to sign each request. For security, we recommend using the secret to calculate the signature and compare. You can find the secret alphanumeric string in the UI after saving or editing a Webhook. Addigy signs the webhook message using the secret key plus the hashing algorithm HMAC-SHA256, encodes the resulting signature in hex, and then includes the signature in the webhook request as a header X-Addigy-Webhook-Payload-Signature.
Event Schema
All events will be returned in the following Schema:
{
"type": "object",
"properties": {
"request_id": {
"type": "string"
},
"webhook_id": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"events": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"event_id": {
"type": "string"
},
"orgid": {
"type": "string"
},
"level": {
"type": "string"
},
"action_sender": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"identifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"identifier",
"name"
]
},
"action": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"details": {
"type": "string"
},
"entity": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"identifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"identifier",
"name"
]
}
},
"required": [
"name",
"details",
"entity"
]
},
"action_receiver": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"identifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"identifier",
"name"
]
},
"result": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"details": {
"type": "string"
}
},
"required": [
"status",
"details"
]
},
"date": {
"type": "string"
}
},
"required": [
"event_id",
"orgid",
"level",
"action_sender",
"action",
"action_receiver",
"result",
"date"
]
},
{
"type": "object",
"properties": {
"event_id": {
"type": "string"
},
"orgid": {
"type": "string"
},
"level": {
"type": "string"
},
"action_sender": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"identifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"identifier",
"name"
]
},
"action": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"details": {
"type": "string"
},
"entity": {
"type": "null"
}
},
"required": [
"name",
"details",
"entity"
]
},
"action_receiver": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"identifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"identifier",
"name"
]
},
"result": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"details": {
"type": "string"
}
},
"required": [
"status",
"details"
]
},
"date": {
"type": "string"
}
},
"required": [
"event_id",
"orgid",
"level",
"action_sender",
"action",
"action_receiver",
"result",
"date"
]
}
]
}
},
"required": [
"request_id",
"webhook_id",
"timestamp",
"events"
]
}
Why did my webhook get disabled?
Addigy automatically disables a webhook after repeated delivery failures:
- Each delivery attempt waits up to 10 seconds for your endpoint to respond. No response in that window counts as a failed attempt.
- Failed attempts are retried with an increasing wait between each one.
- After 10 consecutive failed attempts, the webhook is automatically disabled.
There is currently no notification when this happens. If a webhook drives a downstream action you depend on, check its status periodically on the Integrations page.
If a webhook shows as disabled:
- Confirm your receiving endpoint is online and responds within 10 seconds.
- Re-enable the webhook from the Integrations page.
- Keep an eye on it afterward. One successful delivery doesn't guarantee reliability. If the endpoint is still intermittently slow or unavailable, another 10 consecutive failures will disable it again.