How to Receive IncidentHub Alerts in your Webhook
Introduction
IncidentHub has many integrations to receive alerts. You can choose from Slack, Webhook, Email, Discord, PagerDuty, and more. In this article, we will explore how to receive IncidentHub alerts in your webhooks.
What are Webhooks?
Webhooks are a mechanism to receive notifications over HTTP whenever specific events occur. A common use case is to receive notifications from a third-party when certain events are triggered. Webhooks are an example of a push mechanism, as opposed to a pull mechanism like polling. The benefit of a webhook over a polling mechanism is that you only need to register your webhook URL once.
Using Webhooks For IncidentHub Alerts
IncidentHub has a way to integrate with your webhooks such that you can receive all the usual notifications for incidents, including trigger, update, and resolve events.
Integrating Your Webhook
Integrating your webhook is simple:
- Login to your IncidentHub account.
- Under "My Channels", click on "Add" and then select "Webhook".
- Enter a name and a description for your webhook.
- Enter the webhook URL.
- Click on "Save".
Webhooks are available in IncidentHub's Starter Plan and above. You can sign up directly for a Starter Plan from the website. If you
are already a user on the Free plan, you can upgrade from your IncidentHub account dashboard.
Testing your Webhook
While creating the webhook, you can test if IncidentHub can reach your URL. Enter your webhook URL in the popup and click on "Send a test message". IncidentHub will send a test payload to your webhook URL. If the test is successful, you will see a message "Success" - otherwise you will see an error message. You should also check your webhook server to verify that it received the payload correctly.
The Webhook payload format
IncidentHub sends the payload to the webhook as a JSON in a POST request. The format looks like this:
"type": "updated" | "resolved",
"timestamp": time as a string with time zone indicator,
"data": {
"service": Service name,
"statusPage": Link to the official status page,
"eventURL": Link to the incident,
"content": Content of the incident,
"title": Title of the incident,
}
An example payload looks like this:
{
"type": "updated",
"timestamp": "2024-10-01T22:38:01.725-07:00",
"data": {
"service": "Twilio",
"statusPage": "https://status.twilio.com/",
"eventURL": "https://stspg.io/mjg3188vltfh",
"content": "We are experiencing call dialling delays to InUsually, ydosat Ooredoo Indonesia phone numbers. Our engineers are working with our carrier partner to resolve the issue. We will provide another update in 1 hour or as soon as more information becomes available.",
"title": "Call Dialling Delays To Indosat Ooredoo Indonesia Phone Numbers"
}
}
The Content-Type: application/json header will be set on the request.
Webhook Security
Your webhook must be a secure endpoint as it will called over the public internet. HTTPS is a must. Usually, you will add a secret token to the webhook URL. For example,
https://your-webhook-server.com/webhook/your-secret-token
IncidentHub will directly invoke your webhook URL with the payload. The webhook URL is stored encrypted in our database and is never exposed anywhere, not even to you in the IncidentHub dashboard. You cannot edit your webhook URL once it is created. To make any changes, delete the existing webhook and create a new one.
Webhook Errors
If IncidentHub encounters an error while invoking your webhook, it will send an alert email to the email address that your account is registered with. This is a quick way of notifying you that there was an error. Until you fix the webhook, IncidentHub won't be able to send any notifications to it. Once it is fixed IncidentHub will automatically resume sending notifications.
A sample alert email looks like this:
You should have your own monitoring in place to periodically check your webhook. The IncidentHub webhook failure alert complements your monitoring and is not a substitute.
Best Practices
- Do not share your webhook URL or store it in a publicly accessible place. This includes internal wikis and shared documents in your organization.
- Monitor your email for any alerts from IncidentHub with the subject "Your webhook had errors".
Conclusion
Webhooks are a powerful way to receive IncidentHub alerts. They offer flexibility in integrating with almost any custom tool or system that you want. You can integrate these alerts with your internal monitoring systems, your Internal Developer Portal, or your status dashboard.
You can sign up for a free (forever) IncidentHub account and try it out.
FAQ
Can I add multiple webhooks in my IncidentHub account?
Yes. You can add multiple webhooks to your IncidentHub account. The number of webhooks is only limited by your subscription plan.
What information is sent by IncidentHub in a webhook?
IncidentHub sends all the key details of the incident - the date and time of the incident, the type of the incident, the title, and the URL to the actual incident on the service provider's status page.
When should I choose webhooks to receive IncidentHub alerts?
You can choose webhooks to receive alerts if you want to integrate with your custom tools or systems.
What are the benefits of using webhooks for incident alerts?
Webhooks are a powerful way to receive IncidentHub alerts. They offer flexibility in integrating with almost any tool or system that you want. You can process the webhook payloads the way you want.
How do I ensure security of my webhook?
Do not share your webhook URL or store it in a publicly accessible place. This includes internal wikis and shared repositories in your organization. Ensure that webhooks are only accessible over HTTPS, and have a secure token embedded in the URL.
How do I monitor my webhook?
You can monitor your webhook by checking your email for any alerts from IncidentHub with the subject "Your webhook had errors".
How do I test my webhook before integrating it with IncidentHub?
You can test your webhook by clicking on the "Send a test message" button on the webhook creation popup in the IncidentHub dashboard.
You might also be interested in Integrate Incident Alerts With Discord Using Webhooks