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

# Webhooks

## Overview

Serval allows users to configure webhooks to receive HTTP push notifications when specific events occur in their workspace. These notifications are sent as HTTP POST requests to a user-specified endpoint, enabling real-time integration with external systems and automated workflows.

<Info>
  **API terminology:** The Serval public API and workflow builder use the term **Roles** (previously called "Entitlements"). If you have existing integrations referencing entitlements, update them to use the roles terminology.
</Info>

<Info>
  **Pagination:** All Serval public API endpoints follow [Google AIP-158](https://google.aip.dev/158) pagination standards. List endpoints accept `page_size` and `page_token` parameters and return a `next_page_token` in the response when more results are available.
</Info>

## What are Webhooks?

A webhook is a way for one application to provide real-time information to another application. Instead of requiring constant polling to check for updates, webhooks push data automatically when relevant events occur. This makes them more efficient and responsive than traditional polling methods.

When a configured event happens in Serval, the system automatically sends an HTTP POST request to your specified URL with relevant data about the event.

## Webhook Payload Schema

When an event occurs, Serval sends a JSON payload to your endpoint with the following structure:

```json theme={null}
{
  "id": "<id>",
  "team_id": "<team_id>",
  "timestamp": {
    "seconds": <seconds>,
    "nanos": <nanos>
  },
  "data": {} // JSON object specific to event type - see below
}
```

## Supported Event Types

Currently, only `Copilot Status Change` events will trigger Webhook Push notifications.

### Copilot Status Change Data Payload

```tsx theme={null}
 {
  "ticket_id": "<ticket_id>",
  "thread_id": "<thread_id>",
  "thread_url": "<thread_url>",
  "status": "<status>",
  "reason": "<reason>",
  "pending_workflows": [
    {
      "workflow_id": "<workflow_id>",
      "workflow_name": "<workflow_name>",
      "arguments": "<arguments>"
    }
  ]
 }
```

### Copilot Status Types

The status field in the copilot status change event payload can have the following values:

* `WORKBENCH_STATUS_TYPE_APPROVAL_REQUIRED` - Indicates thread is awaiting approval
* `WORKBENCH_STATUS_TYPE_RESOLVED` - Copilot has resolved the request
* `WORKBENCH_STATUS_TYPE_CANNOT_RESOLVE` - Copilot believes it cannot resolve the request