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
Webhooks are managed on the Integrations page. 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"
]
}