87 lines
5.5 KiB
Plaintext
87 lines
5.5 KiB
Plaintext
---
|
|
title: Webhooks
|
|
image: /images/docs/getting-started/webhooks.png
|
|
info: Descubra como usar nossos Webhooks.
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
|
</Frame>
|
|
|
|
## 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");
|
|
``` |