Webhooks

Use service hooks to receive HTTP webhooks from Sentry when events are created or alerts fire, with HMAC signature verification.

Service hooks let you register HTTP endpoints to receive webhook payloads from Sentry. When a matching event occurs in a Sentry project, Sentry sends a POST request to your URL.

Available events

Service hooks support the following event types:

Event	Description
event.created	Fired when a new error event is ingested.
event.alert	Fired when an issue alert rule is triggered.

Service hooks are for raw events at the project level. For broader event subscriptions (issues, comments, metric alerts, installations), use Sentry Apps instead.

Creating a service hook

1. Navigate to project settings

   In Sentry, go to Settings > Projects > [your project] > Service Hooks.

2. Add a service hook

   Click Add Service Hook and fill in:

   • URL: The HTTPS endpoint where Sentry should send payloads.
   • Events: Select one or more events to subscribe to.
3. Save

   Click Save changes. Sentry generates a secret token for HMAC verification.

Webhook payload structure

event.created

Fired when a new error event is ingested into a project.

{
  "id": "abc123def456",
  "project": "my-project",
  "project_id": "1",
  "project_name": "My Project",
  "culprit": "app.views.index in get",
  "message": "TypeError: Cannot read property 'foo' of undefined",
  "url": "https://sentry.io/organizations/my-org/issues/12345/",
  "level": "error",
  "logger": "",
  "datetime": "2024-01-01T12:00:00.000Z",
  "event": {
    "event_id": "abc123def456",
    "message": "TypeError: Cannot read property 'foo' of undefined",
    "level": "error",
    "platform": "python",
    "timestamp": 1704067200.0,
    "tags": [["environment", "production"], ["release", "1.0.0"]],
    "exception": {
      "values": [
        {
          "type": "TypeError",
          "value": "Cannot read property 'foo' of undefined",
          "stacktrace": {
            "frames": []
          }
        }
      ]
    }
  }
}

event.alert

Fired when an issue alert rule condition is met.

{
  "id": "abc123def456",
  "project": "my-project",
  "project_id": "1",
  "project_name": "My Project",
  "culprit": "app.views.index in get",
  "message": "TypeError: Cannot read property 'foo' of undefined",
  "url": "https://sentry.io/organizations/my-org/issues/12345/",
  "level": "error",
  "triggering_rules": ["Rule Name"]
}

HMAC signature verification

Every webhook request includes an X-Sentry-Hook-Signature header containing an HMAC-SHA256 signature. Verify this signature to confirm the request came from Sentry.

The signature is computed as:

HMAC-SHA256(secret, request_body)

where secret is the token shown in the service hook settings.

Verification examples

verify.py

import hmac
import hashlib

def verify_signature(secret: str, payload: bytes, signature: str) -> bool:
    expected = hmac.new(
        key=secret.encode("utf-8"),
        msg=payload,
        digestmod=hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your request handler:
# body = request.body  # raw bytes
# sig = request.headers["X-Sentry-Hook-Signature"]
# if not verify_signature(MY_SECRET, body, sig):
#     return 401

Always read the raw request body before parsing it. Parsing JSON first may alter the byte representation and cause signature verification to fail.

Responding to webhooks

Your endpoint must return a 2xx HTTP status code within the request timeout. If Sentry receives a non-2xx response or the request times out, it does not retry the delivery.

Accept the webhook immediately and process it asynchronously. This prevents timeouts if your processing logic is slow.

Managing service hooks via API

You can also create and manage service hooks programmatically using the Sentry API.

# Create a service hook
curl -X POST https://sentry.io/api/0/projects/{organization_slug}/{project_slug}/hooks/ \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/sentry-webhook",
    "events": ["event.created", "event.alert"]
  }'

# List service hooks
curl https://sentry.io/api/0/projects/{organization_slug}/{project_slug}/hooks/ \
  -H 'Authorization: Bearer YOUR_TOKEN'