---
title: Webhooks
image: /images/docs/getting-started/webhooks.png
info: Descubra como usar nossos Webhooks.
---
## Visão geral
Os webhooks no Twenty complementam a API permitindo **notificações em tempo real** para suas próprias aplicações quando certos eventos acontecem no seu CRM. Em vez de consultar continuamente a API por alterações, você pode configurar webhooks para que o Twenty **envie** dados para o seu sistema sempre que eventos específicos ocorrerem (por exemplo, quando um novo registro é criado ou um registro existente é atualizado). Isso ajuda a manter os sistemas externos sincronizados com o Twenty de maneira instantânea e eficiente.
Com webhooks, o Twenty enviará uma solicitação HTTP POST para uma URL que você especificar, contendo detalhes sobre o evento. Depois, você pode manipular esses dados em sua aplicação (por exemplo, para atualizar seu banco de dados externo, acionar fluxos de trabalho ou enviar alertas).
## Configurando um Webhook
Para criar um webhook no Twenty, use as configurações de **APIs & Webhooks** no seu aplicativo Twenty:
1. **Navegue até Configurações:** No seu aplicativo Twenty, vá para **Configurações → APIs & Webhooks**.
2. **Crie um Webhook:** Sob **Webhooks** clique em **+ Criar webhook**.
3. **Insira a URL:** Forneça a URL do endpoint no seu servidor onde você deseja que o Twenty envie solicitações de webhook. Esta deve ser uma URL acessível publicamente que possa manejar solicitações POST.
4. **Salvar:** Clique em **Salvar** para criar o webhook. O novo webhook estará ativo imediatamente.
Você pode criar múltiplos webhooks se precisar enviar diferentes eventos para diferentes endpoints. Cada webhook é essencialmente uma inscrição para todos os eventos relevantes (neste momento, o Twenty envia todos os tipos de eventos para a URL fornecida; filtrar tipos específicos de eventos pode ser configurável na UI). Se algum dia precisar remover um webhook, você pode deletá-lo através da mesma página de configurações (selecione o webhook e escolha deletar).
## Eventos e Cargas
Uma vez que um webhook está configurado, o Twenty enviará uma solicitação HTTP POST para a URL especificada sempre que um evento de gatilho ocorrer em seus dados de CRM. Eventos comuns que disparam webhooks incluem:
- **Registro Criado:** por exemplo, uma nova pessoa é adicionada (`person.created`), uma nova empresa é criada (`company.created`), uma nota é criada (`note.created`), etc.
- **Registro Atualizado:** por exemplo, as informações de uma pessoa existente são atualizadas (`person.updated`), um registro de empresa é editado (`company.updated`), etc.
- **Registro Deletado:** por exemplo, uma pessoa ou empresa é deletada (`person.deleted`, `company.deleted`).
- **Outros Eventos:** Se aplicável, outros eventos de objetos ou gatilhos personalizados (por exemplo, se tarefas ou outros objetos forem atualizados, tipos de eventos semelhantes seriam usados como `task.created`, `note.updated`, etc.).
A solicitação POST do webhook contém uma carga JSON em seu corpo. A carga geralmente incluirá pelo menos duas coisas: o tipo de evento e os dados relacionados a esse evento (geralmente o registro que foi criado/atualizado). Por exemplo, um webhook para uma pessoa recém-criada pode enviar uma carga como:
```
{
"event": "person.created",
"data": {
"id": "abc12345",
"firstName": "Alice",
"lastName": "Doe",
"email": "alice@example.com",
"createdAt": "2025-02-10T15:30:45Z",
"createdBy": "user_123"
},
"timestamp": "2025-02-10T15:30:50Z"
}
```
Neste exemplo:
- `"event"` especifica o que aconteceu (`person.created`).
- `"data"` contém os detalhes do novo registro (as mesmas informações que você obteria se solicitasse essa pessoa via API).
- `"timestamp"` indica quando o evento ocorreu (em UTC).
Seu endpoint deve estar preparado para receber tais dados JSON via POST. Geralmente, você irá analisar o JSON, observar o tipo de `"event"` para entender o que aconteceu e então usar os `"data"` conforme necessário (por exemplo, criar um novo contato no seu sistema ou atualizar um existente).
**Nota:** É importante responder com um **status HTTP 2xx** do seu endpoint de webhook para reconhecer o recebimento bem-sucedido. Se o remetente do webhook Twenty não obter uma resposta 2xx, ele pode considerar que a entrega falhou. (No futuro, uma lógica de repetição pode tentar reenviar webhooks falhados, então sempre esforce-se para retornar um 200 OK assim que possível após processar os dados.)
## Validação de Webhook
Para assegurar a segurança dos seus endpoints de webhook, o Twenty inclui uma assinatura no cabeçalho `X-Twenty-Webhook-Signature`.
Essa assinatura é um hash HMAC SHA256 da carga da solicitação, computado usando seu segredo de webhook.
Para validar a assinatura, você precisará:
1. Concatenar o timestamp (do cabeçalho `X-Twenty-Webhook-Timestamp`), uma cólon e a string JSON da carga
2. Computar o hash HMAC SHA256 usando seu segredo de webhook como chave.
3. Comparar o digest em hexadecimal resultante com o cabeçalho da assinatura.
Aqui está um exemplo em Node.js:
```javascript
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
.update(stringToSign)
.digest("hex");
```