Skip to main content
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:
EventDescription
event.createdFired when a new error event is ingested.
event.alertFired 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

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'

Build docs developers (and LLMs) love

Get started for freeTalk to us