# Ricevere messaggi via webhook

Registri un endpoint HTTPS (pannello → Webhook, oppure `POST /webhook-endpoints`) e Connect ti invia in POST una **busta versionata** per ogni evento. ⚠ Il tuo endpoint deve accettare **POST con corpo JSON** (n8n/Make/Zapier impostano il trigger su GET per impostazione predefinita — cambialo in POST). La busta non è il payload grezzo di Meta: se Meta cambia il suo formato, la tua integrazione non si rompe. Header di firma: `X-Connect-Signature-256`, `X-Connect-Timestamp`, `X-Connect-Delivery-Id` (questa consegna a questo endpoint; resta uguale tra un tentativo e l'altro), `X-Connect-Event`. **Deduplica per l'`id` della busta (`evt_…`)**: è lo stesso in tutti i tentativi e in tutti i tuoi endpoint, e una nuova consegna da parte di Meta non ne genera un altro. In un messaggio, va bene anche `data.message.id` (l'id di WhatsApp).

### La busta che inviamo con POST al tuo endpoint

```json
{
  "id": "evt_7f3a1b2c9d4e5f6a7b8c9d0e1f2a3b4c",
  "type": "message.received",
  "version": "1",
  "createdAt": "2026-08-06T00:31:22.461Z",
  "connection": {
    "id": "conn_4eede070e5a84d1590bdce2ea1d837bc",
    "phoneNumber": "+5493510000000",
    "externalId": "farmacia-lopez"
  },
  "sequence": 12345,
  "data": {
    "message": {
      "id": "wamid.HBgL…",
      "from": "5493511234567",
      "type": "text",
      "text": {
        "body": "hola"
      }
    },
    "contacts": [
      {
        "wa_id": "5493511234567",
        "profile": {
          "name": "Ana"
        }
      }
    ]
  }
}
```

### Intestazioni

| Header | Cos'è |

| --- | --- |

| `X-Connect-Event` | The event type (e.g. message.received) — branch on this. |

| `X-Connect-Delivery-Id` | This delivery to this endpoint, stable across retries. To deduplicate events, use the envelope `id` (evt_…): a Meta re-delivery does not produce a new one. |

| `X-Connect-Timestamp` | Unix seconds; part of the HMAC. Reject deliveries older than ~5 min. |

| `X-Connect-Signature-256` | sha256=HMAC(secret, timestamp + '.' + rawBody). Verify before trusting the body. |

| `X-Connect-Token` | Optional static header (if you enabled one) — your tool's native Header Auth checks it. |

## Note

- `connection` arriva SEMPRE come oggetto, ma i suoi campi sono null negli eventi a livello di account (usage.threshold_reached) e in webhook.test.
- Come AUTENTICARE la consegna (header statico o firma): vedi il modulo 'Autenticare il webhook'. Usi n8n? Il workflow da importare è in Integrazioni.