Outgoing webhooks

Integrate Better Stack with your own services by receiving an HTTP request when errors change or a new release is detected.

Setting up a webhook

1. Navigate to Errors → Outgoing webhooks
2. Find Error webhook or Release webhook and click Add.
3. Enter the Webhook URL we should send requests to.
4. For error webhooks, select which events should fire the webhook.
5. Click Create webhook.

Use Send a test webhook to verify your endpoint receives the request.

Webhook events

Error webhook sends a request when the selected error lifecycle events happen:

• New error: an error is seen for the first time.
• Threshold: an error reaches its notification threshold.
• Spike: an error suddenly spikes.
• Reoccurred: a resolved or ignored error comes back.
• Resolved, Ignored, and Unresolved: the error state changes.

Release webhook sends a request when a new release is detected.

Webhook request

Webhooks are sent as HTTP POST requests with a JSON body:

{
  "data": {
    "id": "a1b2c3d4e5",
    "type": "error",
    "attributes": {
      "event": "new_error",
      "application_id": 4821,
      "application_name": "Backend API",
      "team_id": 12345,
      "error_url": "https://errors.betterstack.com/team/12345/errors/a1b2c3d4e5?s=4821",
      "error_type": "ActiveRecord::RecordNotFound",
      "error_message": "Couldn't find User with 'id'=999",
      "call_site_function": "UsersController#show",
      "call_site_file": "app/controllers/users_controller.rb",
      "first_seen": "2026-07-02T09:14:03Z",
      "last_seen": "2026-07-02T09:14:03Z",
      "environment": "production",
      "notify_threshold": null,
      "previous_state": null
    }
  }
}

{
  "data": {
    "id": "5567",
    "type": "release",
    "attributes": {
      "event": "new_release",
      "application_id": 4821,
      "application_name": "Backend API",
      "team_id": 12345,
      "release_ref": "v1.2.3",
      "release_url": "https://errors.betterstack.com/team/12345/releases/5567",
      "first_seen_at": "2026-07-02T09:00:00Z",
      "last_seen_at": "2026-07-02T09:14:00Z",
      "environment": "production"
    }
  }
}

For a threshold event, notify_threshold contains the configured threshold. For a reoccurred event, previous_state is resolved or ignored.

Requests time out after 25 seconds and are retried up to 3 times. Review recent deliveries and responses in the webhook's logs when editing the webhook.

Customizing the request

Open Advanced settings when creating or editing a webhook to customize the request:

• HTTP method: use HEAD, GET, POST, PUT, PATCH, OPTIONS, or DELETE.
• Headers: add custom header names and values.
• Basic HTTP authentication: username and password, stored in an encrypted form.
• Request body template: write your own body using variables like $ERROR_ID, $EVENT, $APPLICATION_NAME, or $ERROR_URL. Available variables are listed under the template field.

Need help?

Please let us know at hello@betterstack.com.
We're happy to help! 🙏