---
title: "Hooks"
description: "Client lifecycle hooks, the on/emit subscription system, user-facing callbacks like before_send and the samplers, and how SDKs isolate errors raised inside them."
url: https://develop.sentry.dev/sdk/foundations/client/hooks/
---

# Hooks | Sentry Docs

This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.

Statuscandidate[](https://develop.sentry.dev/sdk/getting-started/standards/spec-lifecycle.md "Learn about spec statuses")

Version`1.1.0`[(changelog)](https://develop.sentry.dev/sdk/foundations/client/hooks.md#changelog)

## [Overview](https://develop.sentry.dev/sdk/foundations/client/hooks.md#overview)

The Client supports several hook mechanisms for extensibility:

* **Lifecycle hooks** (`on`/`emit`) — an internal event subscription system primarily for integration authors
* **`before_send`** — a user-facing callback for modifying or discarding error events
* **`before_send_transaction`** — a user-facing callback for modifying or discarding transaction events
* **`before_send_check_in`** — an optional callback for modifying or discarding check-in events
* **`before_breadcrumb`** — a user-facing callback for modifying or discarding breadcrumbs

[Callback Error Isolation](https://develop.sentry.dev/sdk/foundations/client/hooks.md#callback-error-isolation) applies to every user-provided callback, including those specified elsewhere: the `before_send_*` variants for each telemetry type, the samplers, and user-registered event processors.

Related specs:

* [Client](https://develop.sentry.dev/sdk/foundations/client.md) — event pipeline, event processors, and capture methods
* [Configuration](https://develop.sentry.dev/sdk/foundations/client/configuration.md) — `before_send`, `before_breadcrumb`, and sampler options
* [Client Reports](https://develop.sentry.dev/sdk/telemetry/client-reports.md) — discard reasons recorded when a callback drops an item

***

## [Behavior](https://develop.sentry.dev/sdk/foundations/client/hooks.md#behavior)

### [Lifecycle Hooks](https://develop.sentry.dev/sdk/foundations/client/hooks.md#lifecycle-hooks)

Candidatespecified since 1.0.0

The Client **SHOULD** support an event subscription system for fine-grained extensibility beyond `before_send` and event processors. This is primarily an internal API for integration authors. (See [RFC 0034](https://github.com/getsentry/rfcs/pull/34).)

```typescript
interface Client {
  on(hookName: string, callback: (...args: unknown[]) => void): void;
  emit(hookName: string, ...args: unknown[]): void;
}
```

Hooks are stateless and called in registration order. Data passed into hooks **MAY** be mutated by callbacks. Available hooks vary by SDK but may include:

* `startSpan` / `finishSpan` — span lifecycle
* `beforeEnvelope` — last chance to inspect/modify outgoing envelopes
* `startSession` / `endSession` — session lifecycle

This system complements — not replaces — the `before_send` hook and event processors. Use hooks when integrations need to react to lifecycle events that are not part of the event pipeline (e.g., span creation).

### [Before-Send Hook](https://develop.sentry.dev/sdk/foundations/client/hooks.md#before-send-hook)

Stablespecified since 1.0.0

Hook called with the event (and on some platforms the hint) that allows the user to decide whether an event should be sent or not. This can also be used to further modify the event. This hook **MUST** only apply to `error` events. Other event types like transactions, check-ins, and feedbacks **MUST NOT** go through `beforeSend` — they have their own dedicated hooks.

In the [event pipeline](https://develop.sentry.dev/sdk/foundations/client.md#event-pipeline), `before_send` is invoked after scope application and event processors, and before the session update. Returning `null` discards the event (client report reason: `before_send`).

### [Before-Send-Transaction Hook](https://develop.sentry.dev/sdk/foundations/client/hooks.md#before-send-transaction-hook)

Stablespecified since 1.0.0

Hook called with the transaction event (and on some platforms the hint) that allows the user to decide whether a transaction should be sent or not. This can also be used to further modify the transaction event. SDKs **SHOULD** support this hook.

This hook **MUST** only apply to transaction events. Returning `null` discards the transaction.

### [Before-Send-Check-In Hook](https://develop.sentry.dev/sdk/foundations/client/hooks.md#before-send-check-in-hook)

Stablespecified since 1.0.0

SDKs **MAY** implement a dedicated `beforeSendCheckIn` hook that applies only to check-in events. Check-in events **MUST NOT** go through the `beforeSend` hook.

See the [Check-Ins spec](https://develop.sentry.dev/sdk/telemetry/check-ins.md#hooks) for full details.

### [Before-Breadcrumb Hook](https://develop.sentry.dev/sdk/foundations/client/hooks.md#before-breadcrumb-hook)

Stablespecified since 1.0.0

Hook called with the breadcrumb (and on some platforms the hint) that allow the user to decide whether and how a breadcrumb should be sent.

### [Callback Error Isolation](https://develop.sentry.dev/sdk/foundations/client/hooks.md#callback-error-isolation)

Candidatespecified since 1.1.0

A user callback failing due to a recoverable error **MUST NOT** break the host application. SDKs **MUST** catch every recoverable error a user-provided callback raises, for example with `try`/`catch` or `rescue`. A rejected promise, future, or task **MUST** be handled like a synchronous raise.

SDKs **SHOULD NOT** recover from intentionally fatal exits, such as Python's `KeyboardInterrupt` and `SystemExit`, Java `Error` subclasses like `OutOfMemoryError`, Rust panics, or C aborts. Recovering from them hides the underlying failure. SDKs whose callback types can't raise recoverable errors, checked at compile time, don't need a runtime boundary.

When a user-provided callback fails due to a recoverable error, SDKs:

* **MUST** emit an error-level [internal log](https://develop.sentry.dev/sdk/foundations/client/configuration.md#debug-mode) naming the callback.
* **MUST NOT** re-throw or capture the error as an event, unless strict mode is enabled.
* **SHOULD** drop the data passed to the callback. For callbacks that do not support dropping data (e.g. `before_send_span`), SDKs **SHOULD** instead send the data to Sentry unchanged.
* **SHOULD** record a client report with reason `callback_error` for all data dropped as a result of the callback error.

SDKs **MAY** offer an opt-in strict mode, disabled by default. In strict mode, a callback failure **MUST** propagate as an unhandled error of the host application instead of being isolated. SDKs **MUST NOT** pass the event reporting that error through the callback that failed. If any callback fails while processing that event, or data the SDK creates while reporting it (such as breadcrumbs), SDKs **MUST** isolate that failure instead of propagating it.

***

## [Changelog](https://develop.sentry.dev/sdk/foundations/client/hooks.md#changelog)

| Version | Date       | Summary                                                                                                                                                                                 |
| ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `1.1.0` | 2026-08-31 | Added callback error isolation requirements, the per-callback failure matrix, and the \`callback\_error\` client report for dropped items; widened scope to all user-provided callbacks |
| `1.0.1` | 2026-08-03 | Clarified before\_send position relative to the session update; requires client spec 3.0.0                                                                                              |
| `1.0.0` | 2025-02-24 | Initial spec, extracted from client spec v2.1.0 and expected features                                                                                                                   |