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

# Criar webhook

> Cria uma nova assinatura de webhook para receber eventos da SocialSell.

## Endpoint

```
POST /v1/webhooks
```

**Escopo necessário:** `write:webhooks`

## Corpo da requisição

| Campo    | Tipo      | Obrigatório | Descrição                         |
| -------- | --------- | ----------- | --------------------------------- |
| `name`   | string    | Sim         | Nome descritivo (máx. 100 chars)  |
| `url`    | string    | Sim         | URL HTTPS de destino              |
| `events` | string\[] | Sim         | Mínimo 1 evento. Ver lista abaixo |

### Eventos disponíveis

| Evento               | Descrição                         |
| -------------------- | --------------------------------- |
| `contact.created`    | Novo contato criado               |
| `contact.updated`    | Contato atualizado                |
| `deal.created`       | Novo negócio criado               |
| `deal.stage.changed` | Negócio mudou de etapa            |
| `deal.won`           | Negócio marcado como ganho        |
| `deal.lost`          | Negócio marcado como perdido      |
| `message.received`   | Nova mensagem recebida de contato |

## Exemplo de requisição

```bash theme={null}
curl -X POST https://api.socialsell.ai/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração CRM Interno",
    "url": "https://meusistema.com/webhook/socialsell",
    "events": ["contact.created", "contact.updated", "deal.won"]
  }'
```

## Exemplo de resposta

```json theme={null}
{
  "data": {
    "id": "664m8n9o0p1q2r3s4t5u6v7w",
    "name": "Integração CRM Interno",
    "url": "https://meusistema.com/webhook/socialsell",
    "events": ["contact.created", "contact.updated", "deal.won"],
    "status": "active",
    "secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6",
    "last_delivery_at": null,
    "last_failure_at": null,
    "consecutive_failures": 0,
    "created_at": "2026-06-10T16:00:00.000Z",
    "updated_at": "2026-06-10T16:00:00.000Z"
  }
}
```

Retorna `HTTP 201`.

<Warning>
  O campo `secret` é exibido **apenas nesta resposta**. Armazene-o imediatamente como variável de ambiente para usar na validação de assinaturas. Não é possível recuperá-lo depois.
</Warning>

## Validando entregas

Use o `secret` para verificar a autenticidade de cada requisição recebida. Veja o [Guia de Webhooks](/api-reference/webhooks-guide#validando-a-assinatura) para exemplos de código.