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

# Webhooks

Manage webhooks to receive real-time event notifications from your G-Tateth account.

## Create Webhook

<Endpoint method="POST" path="/api/v1/webhooks">
  Create a new webhook
</Endpoint>

<ParamField body="name" type="body" required>
  Name for the webhook (1-100 characters)
</ParamField>

<ParamField body="url" type="body" required>
  HTTPS URL where webhook events will be sent
</ParamField>

<ParamField body="events" type="body" required>
  Array of event types to subscribe to (e.g., `["conversation.created", "customer.updated"]`)
</ParamField>

<ParamField body="headers" type="body" optional>
  Custom headers to include with webhook requests (object)
</ParamField>

<ParamField body="retryPolicy" type="body" optional>
  Retry policy configuration:

  ```json theme={null}
  {
    "maxRetries": 3,
    "backoffStrategy": "exponential"
  }
  ```

  * `maxRetries`: Number of retry attempts (0-10)
  * `backoffStrategy`: `"linear"` or `"exponential"`
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data._id" type="string">
  Webhook ID
</ResponseField>

<ResponseField name="data.name" type="string">
  Webhook name
</ResponseField>

<ResponseField name="data.url" type="string">
  Webhook URL
</ResponseField>

<ResponseField name="data.events" type="array">
  Array of subscribed events
</ResponseField>

<ResponseField name="data.secret" type="string">
  Webhook secret for signature verification (only shown once)
</ResponseField>

<ResponseField name="data.isActive" type="boolean">
  Whether the webhook is active
</ResponseField>

<Warning>
  Save the webhook secret immediately - it's only shown once and is required for signature verification!
</Warning>

### Example Request

```bash theme={null}
curl -X POST https://api.g-tateth.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://myapp.com/webhooks/g-tateth",
    "events": ["conversation.created", "conversation.updated", "customer.created"],
    "retryPolicy": {
      "maxRetries": 3,
      "backoffStrategy": "exponential"
    }
  }'
```

## List Webhooks

<Endpoint method="GET" path="/api/v1/webhooks">
  List all webhooks for your tenant
</Endpoint>

<ParamField query="isActive" type="boolean" optional>
  Filter by active status: `true` or `false`
</ParamField>

<ParamField query="page" type="integer" optional>
  Page number (default: 1)
</ParamField>

<ParamField query="limit" type="integer" optional>
  Items per page (default: 20, max: 100)
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data.webhooks" type="array">
  Array of webhook objects
</ResponseField>

<ResponseField name="data.total" type="number">
  Total number of webhooks
</ResponseField>

<ResponseField name="data.page" type="number">
  Current page number
</ResponseField>

<ResponseField name="data.limit" type="number">
  Items per page
</ResponseField>

<ResponseField name="data.totalPages" type="number">
  Total number of pages
</ResponseField>

## Get Webhook

<Endpoint method="GET" path="/api/v1/webhooks/:id">
  Get details of a specific webhook
</Endpoint>

<ParamField path="id" type="string" required>
  Webhook ID
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="object">
  Webhook object (secret is not included)
</ResponseField>

## Update Webhook

<Endpoint method="PUT" path="/api/v1/webhooks/:id">
  Update a webhook
</Endpoint>

<ParamField path="id" type="string" required>
  Webhook ID
</ParamField>

<ParamField body="name" type="body" optional>
  Update webhook name (1-100 characters)
</ParamField>

<ParamField body="url" type="body" optional>
  Update webhook URL (must be HTTPS)
</ParamField>

<ParamField body="events" type="body" optional>
  Update array of subscribed events
</ParamField>

<ParamField body="isActive" type="body" optional>
  Activate or deactivate the webhook
</ParamField>

<ParamField body="headers" type="body" optional>
  Update custom headers
</ParamField>

<ParamField body="retryPolicy" type="body" optional>
  Update retry policy
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="object">
  Updated webhook object
</ResponseField>

## Delete Webhook

<Endpoint method="DELETE" path="/api/v1/webhooks/:id">
  Delete a webhook permanently
</Endpoint>

<ParamField path="id" type="string" required>
  Webhook ID
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<Warning>
  This action cannot be undone! The webhook will stop receiving events immediately.
</Warning>

## Test Webhook

<Endpoint method="POST" path="/api/v1/webhooks/:id/test">
  Send a test event to the webhook URL
</Endpoint>

<ParamField path="id" type="string" required>
  Webhook ID
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="message" type="string">
  "Test webhook event sent"
</ResponseField>

<Note>
  This sends a test event to your webhook URL. Use this to verify your webhook endpoint is working correctly.
</Note>

## Get Webhook Logs

<Endpoint method="GET" path="/api/v1/webhooks/:id/logs">
  Get delivery logs for a webhook
</Endpoint>

<ParamField path="id" type="string" required>
  Webhook ID
</ParamField>

<ParamField query="status" type="string" optional>
  Filter by delivery status: `pending`, `success`, `failed`
</ParamField>

<ParamField query="page" type="integer" optional>
  Page number (default: 1)
</ParamField>

<ParamField query="limit" type="integer" optional>
  Items per page (default: 20, max: 100)
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data.logs" type="array">
  Array of delivery log objects
</ResponseField>

<ResponseField name="data.total" type="number">
  Total number of logs
</ResponseField>

<ResponseField name="data.page" type="number">
  Current page number
</ResponseField>

<ResponseField name="data.limit" type="number">
  Items per page
</ResponseField>

<ResponseField name="data.totalPages" type="number">
  Total number of pages
</ResponseField>

### Log Object Structure

```json theme={null}
{
  "_id": "...",
  "webhookId": "...",
  "event": "conversation.created",
  "status": "success",
  "statusCode": 200,
  "attempt": 1,
  "deliveredAt": "2024-01-01T12:00:00Z",
  "responseTime": 150,
  "error": null
}
```

## Supported Events

### Conversation Events

* `conversation.created` - New conversation created
* `conversation.updated` - Conversation updated
* `conversation.assigned` - Conversation assigned to agent
* `conversation.closed` - Conversation closed

### Customer Events

* `customer.created` - New customer created
* `customer.updated` - Customer updated

### Message Events

* `message.sent` - Message sent
* `message.received` - Message received

### Call Events

* `call.initiated` - Call has been initiated
* `call.answered` - Call has been answered
* `call.completed` - Call has completed
* `call.recording.available` - Call recording is available

## Required Permissions

* `webhook:manage` - Required for all webhook operations

## Webhook Signature Verification

Each webhook request includes an `X-Webhook-Signature` header. Always verify signatures to ensure requests are from G-Tateth.

See the [Webhooks Guide](/guides/webhooks) for signature verification examples in various languages.