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

# Criar Webhook

> Criar uma nova configuração de webhook para um agente

## Visão Geral

Cria uma nova configuração de webhook para um agente. Webhooks permitem receber notificações em tempo real quando eventos específicos ocorrem durante as chamadas.

## Endpoint

<ParamField path="agent_id" type="string" required>
  UUID do agente
</ParamField>

## Requisição

<RequestField name="name" type="string" required>
  Nome legível para o webhook (máximo de 255 caracteres)
</RequestField>

<RequestField name="webhook_url" type="string" required>
  URL para onde os eventos do webhook serão enviados (máximo de 500 caracteres, deve ser uma URL válida)
</RequestField>

<RequestField name="webhook_secret" type="string">
  Secret opcional para verificação de assinatura HMAC-SHA256 (máximo de 255 caracteres). Quando definido, cada entrega de webhook inclui um cabeçalho de assinatura que você pode verificar.
</RequestField>

<RequestField name="events" type="array" required>
  Array de tipos de evento aos quais se inscrever (mínimo de 1 evento obrigatório). Cada evento deve estar na lista de eventos disponíveis retornada por [Listar Webhooks do Agente](/api-reference/endpoints/list-agent-webhooks).
</RequestField>

<RequestField name="timeout" type="integer">
  Timeout da requisição em segundos. Faixa: `5`–`120`. Padrão: `30`.
</RequestField>

<RequestField name="max_retries" type="integer">
  Número máximo de tentativas de retry em caso de falha de entrega. Faixa: `0`–`10`. Padrão: `3`.
</RequestField>

<RequestField name="enabled" type="boolean">
  Se o webhook deve estar ativo. Padrão: `true`.
</RequestField>

<RequestField name="http_method" type="string">
  Método HTTP usado para entregar eventos do webhook. Opções: `POST`, `PUT`, `PATCH`. Padrão: `POST`.
</RequestField>

<RequestField name="authorization_scheme" type="string">
  Esquema de autorização aplicado às requisições de saída. Opções: `none`, `bearer`, `basic`, `api_key`, `custom`. Padrão: `none`.
</RequestField>

<RequestField name="custom_headers" type="array">
  Array de cabeçalhos HTTP customizados a incluir em cada entrega. Cada item: `{ "key": "Header-Name", "value": "header-value" }`. Útil para tokens de auth estáticos ou cabeçalhos de roteamento exigidos pelo seu endpoint.
</RequestField>

<RequestField name="payload_templates" type="object">
  Templates de payload opcionais por evento. Permite sobrescrever a estrutura padrão de payload para eventos específicos. As chaves são nomes de eventos; os valores são objetos de template que suportam interpolação de variáveis (ex: `{{call.id}}`).
</RequestField>

<RequestExample>
  ```bash theme={null}
  curl -X POST \
    'https://app.talkover.ai/api/v1/agents/9fbef0b7-8d4e-4a08-9207-66c22155721d/webhooks' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "My Webhook",
      "webhook_url": "https://example.com/webhook",
      "webhook_secret": "optional_secret_for_hmac",
      "events": ["event_phone_call_started", "event_phone_call_ended"],
      "timeout": 30,
      "max_retries": 3,
      "enabled": true
    }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://app.talkover.ai/api/v1/agents/9fbef0b7-8d4e-4a08-9207-66c22155721d/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'My Webhook',
      webhook_url: 'https://example.com/webhook',
      webhook_secret: 'optional_secret_for_hmac',
      events: ['event_phone_call_started', 'event_phone_call_ended'],
      timeout: 30,
      max_retries: 3,
      enabled: true
    })
  });
  const data = await response.json();
  ```

  ```php theme={null}
  <?php

  $client = new \GuzzleHttp\Client();
  $response = $client->post('https://app.talkover.ai/api/v1/agents/9fbef0b7-8d4e-4a08-9207-66c22155721d/webhooks', [
      'headers' => [
          'Authorization' => 'Bearer YOUR_TOKEN',
          'Content-Type' => 'application/json',
      ],
      'json' => [
          'name' => 'My Webhook',
          'webhook_url' => 'https://example.com/webhook',
          'webhook_secret' => 'optional_secret_for_hmac',
          'events' => ['event_phone_call_started', 'event_phone_call_ended'],
          'timeout' => 30,
          'max_retries' => 3,
          'enabled' => true
      ],
  ]);
  $data = json_decode($response->getBody());
  ```
</RequestExample>

## Resposta

<ResponseField name="success" type="boolean">
  Indica se o webhook foi criado com sucesso
</ResponseField>

<ResponseField name="message" type="string">
  Mensagem de sucesso
</ResponseField>

<ResponseField name="data" type="object">
  Objeto do webhook criado
</ResponseField>

<ResponseField name="data.id" type="string">
  Identificador único do webhook
</ResponseField>

<ResponseField name="data.agent_id" type="string">
  UUID do agente ao qual este webhook pertence
</ResponseField>

<ResponseField name="data.name" type="string">
  Nome do webhook
</ResponseField>

<ResponseField name="data.webhook_url" type="string">
  URL do webhook
</ResponseField>

<ResponseField name="data.events" type="array">
  Array de tipos de evento configurados
</ResponseField>

<ResponseField name="data.timeout" type="integer">
  Timeout da requisição em segundos
</ResponseField>

<ResponseField name="data.max_retries" type="integer">
  Tentativas máximas de retry
</ResponseField>

<ResponseField name="data.enabled" type="boolean">
  Se o webhook está ativo
</ResponseField>

<ResponseField name="data.created_at" type="string">
  Timestamp ISO 8601 quando o webhook foi criado
</ResponseField>

<ResponseField name="data.updated_at" type="string">
  Timestamp ISO 8601 quando o webhook foi atualizado pela última vez
</ResponseField>

<ResponseField name="data.events_count" type="integer">
  Número de eventos configurados para este webhook
</ResponseField>

<ResponseField name="data.status" type="string">
  Status atual do webhook
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Webhook created successfully",
    "data": {
      "id": "9fcafbf2-7593-44d6-8cd7-1b221beba62a",
      "agent_id": "9fbef0b7-8d4e-4a08-9207-66c22155721d",
      "name": "My Webhook",
      "webhook_url": "https://example.com/webhook",
      "events": ["event_phone_call_started", "event_phone_call_ended"],
      "timeout": 30,
      "max_retries": 3,
      "enabled": true,
      "created_at": "2025-09-03T23:19:51.000000Z",
      "updated_at": "2025-09-03T23:19:51.000000Z",
      "events_count": 2,
      "status": "active"
    }
  }
  ```
</ResponseExample>

## Respostas de erro

<ResponseExample title="401 Não Autorizado">
  ```json theme={null}
  {
    "message": "Missing Bearer Token"
  }
  ```
</ResponseExample>

<ResponseExample title="404 Não Encontrado">
  ```json theme={null}
  {
    "success": false,
    "message": "Agent not found in this environment."
  }
  ```
</ResponseExample>

<ResponseExample title="422 Erro de Validação">
  ```json theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "webhook_url": ["The webhook url field is required."],
      "events": ["The events field must contain at least 1 items."]
    }
  }
  ```
</ResponseExample>

## Regras de validação

* **name**: Obrigatório, string, máximo de 255 caracteres
* **webhook\_url**: Obrigatório, URL válida, máximo de 500 caracteres
* **webhook\_secret**: Opcional, string, máximo de 255 caracteres
* **events**: Obrigatório, array com mínimo de 1 evento, cada evento deve estar na lista de eventos disponíveis
* **timeout**: Opcional, inteiro entre 5-120 segundos (padrão: 30)
* **max\_retries**: Opcional, inteiro entre 0-10 (padrão: 3)
* **enabled**: Opcional, booleano (padrão: true)

## Observações importantes

* Operações de webhook limpam automaticamente o cache do agente para efeito imediato
* Use endpoints HTTPS para URLs de webhook em produção
* Implemente verificação adequada de assinatura usando o webhook secret para segurança
* Teste seu endpoint de webhook antes de entrar em produção usando o endpoint de teste

## Endpoints relacionados

* [Listar Webhooks do Agente](/api-reference/endpoints/list-agent-webhooks) - Obter todos os webhooks de um agente
* [Obter Detalhes do Webhook](/api-reference/endpoints/get-webhook-details) - Recuperar informações de um webhook específico
* [Atualizar Webhook](/api-reference/endpoints/update-webhook) - Modificar a configuração do webhook
* [Excluir Webhook](/api-reference/endpoints/delete-webhook) - Remover a configuração do webhook
* [Alternar Status do Webhook](/api-reference/endpoints/toggle-webhook-status) - Habilitar/desabilitar webhook
* [Testar Webhook](/api-reference/endpoints/test-webhook) - Enviar payload de teste para verificar conectividade