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

# Introdução aos Webhooks

> Receba notificações automáticas da SocialSell sempre que algo importante acontecer no seu CRM.

Webhooks são a forma mais eficiente de integrar a SocialSell com sistemas externos. Em vez de a sua aplicação ficar perguntando para a API a cada segundo se algo mudou, a SocialSell avisa você imediatamente quando um evento ocorre.

> "Pense nos webhooks como mensagens enviadas pela SocialSell para o seu sistema, sem que você precise ficar consultando a API o tempo todo."

## Por que usar webhooks?

Sem webhooks, a sua aplicação precisaria fazer **polling** constante:

> "Esse contato foi atualizado?" — não.
> "E agora?" — não.
> "E agora?" — sim.

Isso é lento, caro em requisições e ainda assim pode perder eventos. Com webhooks, a SocialSell avisa você **imediatamente** assim que o evento acontece.

Com isso você pode:

* Sincronizar contatos criados na SocialSell com seu ERP ou CRM interno
* Atualizar um negócio no seu sistema quando ele é ganho ou perdido
* Disparar automações (e-mail, Slack, sistemas internos) quando uma mensagem é recebida
* Registrar movimentações de funil em ferramentas de analytics
* Acionar integrações via Zapier, n8n, Make ou código próprio

## Como funciona na prática

<Steps>
  <Step title="Crie uma assinatura">
    Registre um endpoint HTTPS público no seu sistema via `POST /v1/webhooks`, informando os eventos que deseja receber.
  </Step>

  <Step title="A SocialSell envia o evento">
    Quando o evento ocorrer, a SocialSell faz um `POST` para a sua URL com o payload do evento em JSON.
  </Step>

  <Step title="Você valida e processa">
    Valide a assinatura HMAC para confirmar que o evento veio da SocialSell, processe o payload e responda com `200 OK`.
  </Step>

  <Step title="Retentativas automáticas">
    Se seu endpoint não responder ou retornar erro, a SocialSell tentará novamente com backoff exponencial.
  </Step>
</Steps>

## Criando sua primeira assinatura

Requer o escopo `write:webhooks` e plano **Growth ou superior**.

```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 ERP",
    "url": "https://meusistema.com/webhooks/socialsell",
    "events": ["contact.created", "deal.won", "deal.stage.changed"]
  }'
```

A resposta inclui o campo `secret` — armazene-o com segurança, pois ele não será exibido novamente:

```json theme={null}
{
  "data": {
    "id": "664f1a2b3c4d5e6f78901234",
    "name": "Integração ERP",
    "url": "https://meusistema.com/webhooks/socialsell",
    "events": ["contact.created", "deal.won", "deal.stage.changed"],
    "status": "active",
    "secret": "whsec_a1b2c3d4e5f6...",
    "created_at": "2026-06-10T15:00:00.000Z"
  }
}
```

<Warning>
  O campo `secret` é retornado **apenas na criação** e não pode ser recuperado depois. Armazene-o imediatamente como variável de ambiente no seu sistema.
</Warning>

## Formato do payload

Todo evento tem o mesmo envelope:

```json theme={null}
{
  "id": "evt_01jx8kz3m4n5p6q7r8s9t0u1v",
  "event": "deal.won",
  "organization_id": "664a1b2c3d4e5f6789012345",
  "created_at": "2026-06-10T15:30:00.000Z",
  "data": {
    ...
  }
}
```

| Campo             | Tipo   | Descrição                                  |
| ----------------- | ------ | ------------------------------------------ |
| `id`              | string | ID único do evento — use para deduplicação |
| `event`           | string | Nome do evento (ex: `deal.won`)            |
| `organization_id` | string | ID da organização                          |
| `created_at`      | string | Timestamp ISO 8601 do momento do evento    |
| `data`            | object | Payload específico do evento               |

## Eventos disponíveis

| Evento                                                      | Descrição                               |
| ----------------------------------------------------------- | --------------------------------------- |
| [`contact.created`](/webhooks/events/contact-created)       | Um novo contato foi criado              |
| [`contact.updated`](/webhooks/events/contact-updated)       | Um contato foi atualizado               |
| [`deal.created`](/webhooks/events/deal-created)             | Um novo negócio foi criado              |
| [`deal.stage.changed`](/webhooks/events/deal-stage-changed) | Um negócio mudou de etapa no funil      |
| [`deal.won`](/webhooks/events/deal-won)                     | Um negócio foi marcado como ganho       |
| [`deal.lost`](/webhooks/events/deal-lost)                   | Um negócio foi marcado como perdido     |
| [`message.received`](/webhooks/events/message-received)     | Uma mensagem foi recebida de um contato |

## Próximos passos

<CardGroup cols={3}>
  <Card title="Segurança" icon="shield" href="/webhooks/security">
    Como validar a assinatura HMAC de cada entrega.
  </Card>

  <Card title="Política de entregas" icon="refresh-cw" href="/webhooks/delivery">
    Timeouts, retentativas e desativação automática.
  </Card>

  <Card title="Gerenciar assinaturas" icon="settings" href="/api-reference/webhooks/list">
    Endpoints CRUD para gerenciar suas assinaturas.
  </Card>
</CardGroup>