Integrating Webhooks with Locale

Everything you need to know about integrating your alerts with a webhook endpoint of your choice.

We are excited to announce the addition of a new notification channel - Webhooks! With this new action, users can integrate their alerts with a webhook endpoint of their choice. A webhook request will be sent to the endpoint specified by the user whenever an incident event occurs on Locale.

‍

What you can do with this integration?

Instantly receive updates about events as they happen through via webhook endpoint.
Users can now customize downstream notifications by implementing custom logic based on the raw event data.

‍

How to set up a webhook?

When creating an alert (or editing an existing alert):

Select webhook from the list of notification channels.

Select the event type for which you want to receive a webhook request.
- New Incidents: whenever a new incident of this alert is created or resolved locale will send a webhook request to the given endpoint
- Escalated Incidents: Whenever any incident of this alert is escalated locale will send a webhook request to the given endpoint
Enter your webhook endpoint in the textbox. It has to be a fully qualified link i.e URL should include the protocol (such as "https://" or "http://")
Once the above-mentioned details are filled in, you can test the setup by clicking on Send Test Notification the button which will send a dummy payload to the webhook endpoint.

‍

Webhook Payload Fields

Unique identifier of the alert.

Field	Value	Description	Nullable
`event_type`	`incidents.created`/`incidents.escalated`/`incidents.resolved`	Indicates the type of incident event that has triggered the webhook request.	❌
`org_id`		Unique identifier of the organization that the incident belongs to.	❌
`occured_at`		Timestamp of when the incident event occurred.	❌
`data`		An object that contains details about the webhook event.	❌
`data.name`		Name of the incident.	❌
`data.id`		Unique identifier of the incident.	❌
`data.status`	`Closed`/`Unresolved`/`Resolved`	Current status of the incident.	❌
`data.priority`	`Low`/`Medium`/`High`	The priority level of an incident.	✅
`data.incident_link`		URL of the incident.	❌
`data.user_assigned`		An object which contains information about the user assigned to the incident.	✅
`data.user_assigned.id`		Unique identifier of the assigned user.	✅
`data.user_assigned.name`		Name of the assigned user.	✅
`data.user_assigned.email`		Email of the assigned user.	✅
`data.user_assigned.avatar`		Profile picture of the assigned user.	✅
`data.team`		An object which contains information about the team to which the incident is assigned.	✅
`data.team.id`		Unique identifier of the team.	✅
`data.team.name`		Name of the team.	✅
`data.alert`		An object which contains information about the alert to which the incident belongs.	❌
`data.alert.id`		❌
`data.alert.name`		Name of the alert.	❌
`data.escalation`		An object which contains information about the escalation config. The object is not present if the escalation config is not set up for the alert.	✅
`data.escalation.is_escalated`	`true`/`false`	Indicates whether the incident has been escalated.	✅
`data.escalation.escalated_time_threshold`		Threshold time in minutes for escalation of the incident.	✅
`data.escalation.escalated_to`		An object which contains information about the user to which the incident is escalated.	✅
`data.escalation.escalated_to.id`		Unique identifier of the escalated user.	✅
`data.escalation.escalated_to.name`		Name of the escalated user.	✅
`data.escalation.escalated_to.email`		Email of the escalated user.	✅
`data.escalation.escalated_to.avatar`		Profile picture of the escalated user.	✅
`data.payload`		An object which contains information about the query result of the incident.	❌
`data.payload.type`	`url`/`json`	Type of the payload. In the case of `url` type, a signed URL is provided which contains a `csv` file of the query result. In the case of `json` type, the query result is shared as a JSON object.	❌
`data.payload.row_count`		Number of rows in the query result.	❌
`data.payload.data`		Query results as a JSON object. This field is present only if `type` is `json`.	✅
`data.payload.url`		URL to the CSV file which contains query results. This field is present only if `type` is `url`. The signed URL will expire after 3 months.	✅

💡 Locale will make a POST request to the webhook endpoint.

‍

An example of a webhook payload:

Code Display Example


{
 "payload": {
   "event_type": "incident.created",
   "org_id": "34cb66d7-369a-4762-88e9-e4a92505dfec",
   "resource": "incident",
   "occured_at": "2023-01-23 13:30:14.686357",
   "data": {
   "name": "Clubbed incident test",
     "id": "0bbf73de-d473-469e-88b3-fa6d3889846e",
     "status": "Unresolved",
     "priority": "Medium",
     "incident_link": "https://go.locale.ai/xxx/incidents/xxx",
     "alert": {
       "resource": "alert",
       "id": "e4c062f8-e2b9-4dfe-8b64-1ea0e28aa23e",
       "name": "Alert Name"
     },
     "payload": {
       "type": "url",
       "row_count": 10,
       "url": "https://tesseract.locale.ai/results/query_data?incident_id=0bbf73de-d473-469e-886d3889846e&expiry=1682370012636&token=p779LLusIUg5nBXtx192txB7ZL9ND%2BC4%2FJDkQ4eKhhas%2FJjw9OZXfJT9elvOSl2Z7Q%3D%3D"
     },
     "user_assigned": {
       "resource": "user",
       "id": "4e3661d4-a883-4566-bb50-289b30b728dc",
       "name": "Nishit Patel",
       "email": "nishit@locale.ai",
       "avatar": "http://storage.googleapis.com/avatar_store_locale/05.jpg"
     },
     "team": {
       "resource": "team",
       "id": "11e1823f-a9d2-4ec3-b6c6-c8bb11cf2b8f",
       "name": "Bangalore Team"
     }
   }
 }
}

‍

To conclude, the new webhook notification channel allows users to integrate their alerts with any webhook endpoint, providing real-time information on incidents.

Happy Alerting 🙌🏻