> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Callbacks

> Configure SDK callback functions for URL changes, socket events, and auto-capture events to customize Userpilot behavior.

## Options

| Key              | Arguments                                 | Description                                                                                   | Example                                         |
| ---------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `on_url_change`  | `(page: {hostname: string; url: string})` | Fired on each call for the reload method.                                                     | `on_url_change: (page) => console.log(page)`    |
| `on_socket`      | `(event: {event: string; time: number})`  | Fired on socket lifecycle events (`channelJoin`, `joinChannelError`, `unmonitor`, `onError`). | `on_socket: (e) => console.log(e)`              |
| `on_autocapture` | `(payload: Object, type: string)`         | Fired when an auto-captured event occurs (`click`, `submit`, `change`).                       | `on_autocapture: (el,t) => console.log({el,t})` |

***

## Example: Handling Callbacks

```js theme={null}
callbacks: {
  on_url_change: (page) => {
    console.log(page); // {hostname: HOSTNAME, url: URL}
  },
  on_socket: (event) => {
    console.log(event); // {event: channelJoin | joinChannelError | unmonitor | onError, time: TIMESTAMP}
  },
  on_autocapture: (payload, type) => {
    console.log(element_chain, type); // {element: Object, type: click | submit | change}
  }
}
```

```js theme={null}
// Masking page view url call
callbacks: {
  on_url_change: (page = {url, hostname}) => {
    page.hostname = "https://example.com"
    page.url = `${page.hostname}${new URL(page.url).pathname}`
  }
}
```

```js theme={null}
// logging element

const maskAutoCaptureURLs = (payload, key) => {
  console.log(payload[key]);
  
  return payload[key];
}

....

callbacks: {
  on_autocapture: (payload, type) => {
    const maskedKeys = ['href', 'elements_chain'];
    
    maskedKeys.forEach(key => {
      payload[key] = maskAutoCaptureURLs(payload, key)
    })
  }
}
```

***

## Type definitions

```ts theme={null}
type CallbacksConfig = {
  on_url_change?: (page: { hostname: string; url: string }) => void;
  on_socket?: (event: { event: "channelJoin" | "joinChannelError" | "unmonitor" | "onError"; time: number }) => void;
  on_autocapture?: (element: Element, type: "click" | "submit" | "change") => void;
};
```

***

## Troubleshooting

* **“My callback doesn’t fire”** – Ensure the SDK is initialized with `callbacks` defined before events occur.
* **“Socket events not showing”** – Verify network connections and channel join logic.
* **“Autocapture callback too noisy”** – Combine with `excluded_elements` or `masked_elements` to reduce unwanted triggers.