​
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.

​
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: 
{
  "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

 {
  "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