twenty/packages/twenty-docs/l/ca/developers/api-and-webhooks/webhooks.mdx

---
title: Webhooks
image: /images/docs/getting-started/webhooks.png
info: Descobreix com utilitzar els nostres Webhooks.
---

<Frame>
  <img src="/images/docs/getting-started/webhooks.png" alt="Header" />
</Frame>

## Visió general

Els Webhooks en Twenty complementen l'API permetent **notificacions en temps real** a les teves aplicacions quan ocorren certs esdeveniments al CRM. En lloc de consultar contínuament l'API per a canvis, pots configurar webhooks perquè Twenty **empenyi** les dades al teu sistema cada vegada que es produeixen esdeveniments específics (per exemple, quan es crea un registre nou o s'actualitza un registre existent). Això ajuda a mantenir els sistemes externs sincronitzats amb Twenty de manera instantània i eficient.

Amb els webhooks, Twenty enviarà una sol·licitud HTTP POST a una URL que especifiquis, contenint detalls sobre l'esdeveniment. Aleshores pots gestionar aquestes dades a la teva aplicació (per exemple, per actualitzar la teva base de dades externa, activar fluxos de treball, o enviar alertes).

## Configuració d'un Webhook

Per crear un webhook a Twenty, utilitza la configuració de **APIs & Webhooks** a la teva aplicació Twenty:

1. **Navega a Configuració:** A la teva aplicació Twenty, va a **Configuració → APIs & Webhooks**.
2. **Crea un Webhook:** Sota **Webhooks** fes clic a **+ Crear webhook**.
3. **Introdueix la URL:** Proporciona la URL de destinació al teu servidor on vols que Twenty enviï sol·licituds de webhook. Aquesta hauria de ser una URL pública accessible que pugui gestionar sol·licituds POST.
4. **Desa:** Fes clic a **Desa** per crear el webhook. El nou webhook estarà actiu immediatament.

Pots crear múltiples webhooks si necessites enviar diferents esdeveniments a diverses destinacions. Cada webhook és essencialment una subscripció per a tots els esdeveniments rellevants (actualment, Twenty envia tots els tipus d'esdeveniments a la URL donada; potser configurar filtres específics de tipus d'esdeveniments sigui possible a la interfície d'usuari). Si alguna vegada necessites eliminar un webhook, pots suprimir-lo des de la mateixa pàgina de configuracions (selecciona el webhook i tria eliminar).

## Esdeveniments i Càrregues

Un cop configurat un webhook, Twenty enviarà una sol·licitud HTTP POST a la URL especificada cada vegada que es produeixi un esdeveniment desencadenant en les dades del teu CRM. Esdeveniments comuns que activen webhooks inclouen:

- **Registre Creat:** per exemple, s'afegeix una persona nova (`person.created`), es crea una empresa nova (`company.created`), es crea una nota (`note.created`), etc.
- **Registre Actualitzat:** per exemple, es modifica la informació d'una persona existent (`person.updated`), es modifica un registre d'empresa (`company.updated`), etc.
- **Registre Eliminat:** per exemple, s'elimina una persona o empresa (`person.deleted`, `company.deleted`).
- **Altres Esdeveniments:** Si és aplicable, altres esdeveniments d'objectes o activadors personalitzats (per exemple, si es modifiquen tasques o altres objectes, s'utilitzarien tipus d'esdeveniments similars com `task.created`, `note.updated`, etc.).

La sol·licitud POST del webhook conté una càrrega JSON en el seu cos. La càrrega inclourà generalment almenys dues coses: el tipus d'esdeveniment i les dades relacionades amb aquest esdeveniment (sovint el registre que va ser creat / actualitzat). Per exemple, un webhook per a una persona acabada de crear podria enviar una càrrega com:

```
{
  "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"
}
```

En aquest exemple:

- `"event"` especifica què va succeir (`person.created`).
- `"data"` conté els detalls del nou registre (la mateixa informació que obtindries si sol·licitessis aquella persona a través de l'API).
- `"timestamp"` és quan va ocórrer l'esdeveniment (en UTC).

El teu punt final ha d'estar preparat per rebre dades JSON mitjançant POST. Normalment, analitzaràs el JSON, miraràs el tipus de `"event"` per entendre què va passar, i després utilitzaràs les `"data"` en conseqüència (per exemple, crear un nou contacte en el teu sistema o actualitzar-ne un existent).

**Nota:** És important respondre amb un **estat HTTP 2xx** des del teu punt final del webhook per reconèixer la recepció correcta. Si l'emissor del webhook de Twenty no rep una resposta 2xx, pot considerar que el lliurament ha fallat. (En el futur, una lògica de reintent podria intentar reenviar els webhooks fallits, així que intenta retornar un 200 OK tan ràpidament com sigui possible després de processar les dades.)

## Validació del Webhook

Per garantir la seguretat dels teus punts de connexió de webhooks, Twenty inclou una signatura en la capçalera `X-Twenty-Webhook-Signature`.

Aquesta signatura és un hash HMAC SHA256 de la càrrega de la sol·licitud, calculat utilitzant el secret del teu webhook.

Per validar la signatura, necessitaràs:

1. Concatena el timestamp (de la capçalera `X-Twenty-Webhook-Timestamp`), dos punts, i la cadena JSON de la càrrega
2. Calcula el hash HMAC SHA256 utilitzant el secret del teu webhook com a clau ()
3. Compara el digest hexadecimal resultant amb la capçalera de la signatura

Aquí tens un exemple en 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");
```