Ask A BotWebhooks
We've built an example application to help you get started with building on Sentry's integration platform. Check it out for useful code snippets for adding these features in Python and TypeScript. See the docs for more information.
Webhooks are a way for two applications or services to communicate over the web, allowing one application to send automatic notifications or data updates to another in near real-time.
The concept is based on HTTP callbacks, where an HTTP POST request is sent to a specific URL (an HTTP endpoint in your tech stack) with a payload. Sentry uses JSON webhooks to get error notifications to your systems or services.
Sentry webhooks support various functionalities and are made up of four integral HTTP headers described below:
{
"Content-Type": "application/json",
"Request-ID": "<request_uuid>",
"Sentry-Hook-Resource": "<resource>",
"Sentry-Hook-Timestamp": "<timestamp>",
"Sentry-Hook-Signature": "<generated_signature>"
}
The Content-Type header identifies the media type of the payload as JSON format. The Request-ID header provides a unique identifier for tracking and debugging specific events.
This header lets you know which resource from the list below triggered an action:
installationevent_alertissuemetric_alerterrorcomment
This header represents a cryptographic hash generated by your Client Secret. Its primary purpose is to make sure the request is authentic and comes from Sentry servers.
Verifying the Signature
The below code snippet lets you validate the signature with the event payload.
const crypto = require("crypto");
function verifySignature(request, secret = "") {
const hmac = crypto.createHmac("sha256", secret);
hmac.update(JSON.stringify(request.body), "utf8");
const digest = hmac.digest("hex");
return digest === request.headers["sentry-hook-signature"];
}
All webhook requests have some common elements.
action
The action that corresponds with the resource in the header. For example, if the resource is issue the action could be created.
installation
An object with the uuid of the installation so that you can map the webhook request to the appropriate installation.
data
The data object contains information about the resource and will differ in content depending on the type of webhook. This payload may be able to be customized via UI components.
actor
The actor is who, if anyone, triggered the webhook. If a user in Sentry triggered the action, the actor is the user. If the Sentry integration itself triggers the action, the actor is the integration. If the action is triggered automatically within Sentry, the actor is "Sentry".
# Sample cases:
# User installs Sentry integration
"actor": {
"type": "user",
"id": <user-id>,
"name": <user-name>,
}
# Sentry integration makes request to assign an issue
"actor": {
"type": "application",
"id": <sentry-app-uuid>,
"name": <sentry-app-name>,
}
# Sentry (sentry.io) auto resolves an issue
"actor": {
"type": "application",
"id": "sentry",
"name": "Sentry",
}
Webhooks should respond within 1 second. Otherwise, the response is considered a timeout. If a webhook has 1000 timeouts within 24 hours, the webhook will be unsubscribed from receiving events.
If you’d like to test webhook configuration and look at payloads before starting development, an HTTP catch-all service that provides a designated URL where you can receive HTTP payloads and inspect the JSON event payload can come in handy. After you’ve reviewed the relevant event payloads, you can begin development.
To make testing and debugging webhooks faster and easier, you can create local tunnels to get incoming webhook requests from Sentry to your local machine. There are various tools that let you pick a port or address (such as 3000 or 8080) to be tunneled, and then provide you with a temporary public URL that forwards requests to your local server.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").