# Configura un webhook

> Crea un endpoint webhook, scegli i suoi eventi, aggiungi filtri sul payload, invia un evento di test, attiva o disattiva il webhook e ruota il secret.

Questa guida crea un webhook, lo limita agli eventi che ti servono e controlla che il tuo endpoint riceva richieste firmate. Puoi fare tutto nel pannello o con l’[API dei webhook](/it/docs/api-reference/webhooks/).

## Prima di iniziare

- Un URL pubblico che accetti richieste `POST`. HTTPS è fortemente consigliato. Gli URL su `localhost` o su intervalli di IP privati vengono rifiutati; per lo sviluppo in locale, usa un tunnel come ngrok o Cloudflare Tunnel.
- Un endpoint che conservi il corpo grezzo della richiesta, così da poter [verificare la firma](/it/docs/webhooks/request-signature/).
- Per l’API, una chiave con **Full Access**.
- Uno slot libero per un webhook. Pay as you go include 3 endpoint, Pro 10, Business e Custom 100.

## Crea il webhook

**Pannello**

  1. **Apri la pagina Webhooks.** Vai a **Email API → Webhooks** e seleziona **Add webhook**.

  2. **Inserisci un nome e un URL.** Il nome deve essere unico nel workspace, ad esempio `Production events`. L’URL è il tuo endpoint, ad esempio `https://acme.com/webhooks/emailit`. Seleziona **Create**.

  3. **Copia il secret.** La finestra mostra il secret del webhook, che inizia con `whsec_`, insieme all’avviso «You can see the webhook secret only once. Store it safely.» Copialo nell’ambiente della tua app, ad esempio come `EMAILIT_WEBHOOK_SECRET`, e seleziona **Done**.

  Un webhook creato nel pannello sottoscrive tutti i tipi di evento. Si apre la scheda **Settings** del webhook, così puoi restringere la selezione.

**API**

  Chiama [Crea un webhook](/it/docs/api-reference/webhooks/create/). Elenca i tipi di evento in `events`, oppure imposta `all_events` su `true`. La risposta `201` include il `secret`.

```bash
curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://acme.com/webhooks/emailit",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'
```

  A differenza del pannello, l’API usa come valori predefiniti `all_events: false` e una lista `events` vuota, quindi un webhook creato senza nessuno dei due non riceve nulla. Un nome duplicato restituisce `409`; se raggiungi il limite di endpoint del piano, la risposta è `422` con `usage.used` e `usage.limit`.

## Scegli gli eventi

Un webhook riceve tutti i tipi di evento oppure solo quelli che selezioni.

**Pannello**

  Nella scheda **Settings** del webhook, disattiva **All events**, poi seleziona i tipi nel riquadro **Events**. Gli eventi sono raggruppati per risorsa (**Emails**, **Domains**, **Audiences**, **Subscribers**, **Contacts**, **Templates**, **Suppressions**, **Email Verifications**, **Email Verification Lists**) e ogni gruppo ha una casella **Select all**. Seleziona **Save**.

  Il selettore non elenca tutti i tipi che Emailit invia. `email.canceled`, `email.held`, `email.unsubscribed`, `email.resubscribed`, `subscriber.resubscribed` e gli eventi `campaign.*` arrivano ai webhook che hanno **All events** attivo, oppure puoi aggiungerli alla lista con l’API. Il gruppo **Deprecated** contiene vecchi nomi di eventi che non vengono più inviati. Vedi [Tipi di evento](/it/docs/webhooks/event-types/).

**API**

  Chiama [Aggiorna un webhook](/it/docs/api-reference/webhooks/update/). `events` sostituisce l’intera lista. Se imposti `all_events` su `true`, la lista viene svuotata.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all_events": false, "events": ["email.received", "email.held", "email.canceled"]}'
```

## Filtra gli eventi per payload

Pro, Business, Custom

Un filtro sul payload consegna un evento solo quando i suoi dati corrispondono alle tue regole. I filtri si applicano in aggiunta alla selezione degli eventi: un evento deve essere sottoscritto *e* corrispondere al filtro.

Usalo per dividere il traffico tra più endpoint, ad esempio un webhook per ogni linea di prodotto, o per scartare eventi che altrimenti ignoreresti nel codice.

- **Modalità di corrispondenza:** **All rules match** (`all`) oppure **Any rule matches** (`any`).
- **Regole:** fino a 25. Ogni regola ha un campo, un operatore e un valore.
- **Campo:** un percorso con punti all’interno del `data.object` dell’evento, ad esempio `to`, `status`, `meta.plan` o, per gli eventi di clic, `link.url`. Il prefisso `payload.` è facoltativo, quindi `payload.from` e `from` sono equivalenti.
- **I confronti distinguono tra maiuscole e minuscole** e confrontano i valori come testo, tranne `greater_than` e `less_than`, che confrontano numeri.

| Operatore | Corrisponde quando il campo |
| --- | --- |
| `equals` / `not_equals` | È / non è esattamente il valore. |
| `contains` / `not_contains` | Contiene / non contiene il valore. |
| `starts_with` / `ends_with` | Inizia / finisce con il valore. |
| `greater_than` / `less_than` | È un numero maggiore / minore del valore. |
| `is_set` / `is_not_set` | Ha un valore non vuoto / manca o è vuoto. Non serve un valore. |
| `in` / `not_in` | È uguale / non è uguale a uno dei valori di un array. Invia l’array con l’API, come nell’esempio qui sotto. |

**Pannello**

  Nella scheda **Settings** del webhook, trova il riquadro **Filter**. Scegli la modalità di corrispondenza, aggiungi regole con campo, operatore e valore, e seleziona **Save**. Lascia vuote le regole per consegnare tutti gli eventi sottoscritti. Con Pay as you go, il riquadro è bloccato e mostra **Upgrade**.

**API**

  Invia `filter` con [Crea un webhook](/it/docs/api-reference/webhooks/create/) o [Aggiorna un webhook](/it/docs/api-reference/webhooks/update/). Impostalo su `null` per rimuoverlo. Con Pay as you go, un filtro restituisce `403` con `"error": "plan_required"`.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": "all",
      "rules": [
        { "field": "to", "operator": "ends_with", "value": "@acme.com" },
        { "field": "meta.plan", "operator": "in", "value": ["pro", "business"] }
      ]
    }
  }'
```

Altri esempi:

| Obiettivo | Regola |
| --- | --- |
| Solo la posta ricevuta su un indirizzo | `to` `equals` `support@inbound.acme.com` |
| Solo un dominio mittente | `from` `ends_with` `@billing.acme.com` |
| Solo le email che hai etichettato con i metadati | `meta.source` `equals` `checkout` |
| Solo i clic sulla tua pagina dei prezzi | `link.url` `starts_with` `https://acme.com/pricing` |
| Solo le email che contengono un ID cliente | `meta.customer_id` `is_set` |

> **I campi cambiano da un tipo di evento all’altro:** Una regola su un campo che l’evento non ha non trova mai corrispondenza. Gli eventi di stato delle email hanno `to` e `from` al primo livello, ma gli eventi di clic e di caricamento li annidano come `email.rcpt_to` e `email.mail_from`, e gli eventi dei contatti hanno `email`. Con **All rules match**, un webhook filtrato su `to` scarta senza avvisi tutti i clic. Usa webhook separati per ogni tipo di evento, oppure **Any rule matches** con una regola per ogni struttura. Controlla i nomi dei campi nel [riferimento eventi](/it/docs/webhooks/event-types/).

Se un workspace passa a Pay as you go, i filtri esistenti restano salvati ma vengono ignorati, e tutti gli eventi sottoscritti vengono consegnati.

## Invia un evento di test

Un test invia subito un evento di esempio al tuo URL, firmato con il secret attuale del webhook. Gli eventi sottoscritti e i filtri vengono ignorati, la richiesta non viene ritentata e non compare nella scheda **Requests**. Ogni webhook consente 5 test al minuto.

**Pannello**

  Nella pagina del webhook, apri il menu delle azioni (**…**) e seleziona **Send test**. Scegli un tipo di evento e seleziona **Send test**. La finestra mostra «Your endpoint returned 200» (o lo stato restituito dal tuo endpoint) e il corpo della risposta. «Could not reach the endpoint» significa che la richiesta non ha ricevuto una risposta HTTP, ad esempio per un errore DNS, un timeout o un reindirizzamento.

**API**

  Chiama [Invia un evento di test](/it/docs/api-reference/webhooks/test/) con un tipo di evento qualsiasi.

```bash
curl https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "email.delivered"}'
```

  La risposta contiene `ok`, `status_code`, `body` (la risposta del tuo endpoint, fino a 2000 caratteri), `type` e il `payload` inviato.

Gli eventi di test usano dati di esempio, con un `event_id` che inizia con `evt_test_`, e la loro struttura può differire leggermente da quella degli eventi reali. Scrivi l’handler basandoti sul [riferimento eventi](/it/docs/webhooks/event-types/) e confermalo con un invio reale.

## Attiva o disattiva un webhook

Disattiva un webhook per interrompere le consegne senza perderne le impostazioni, ad esempio durante una manutenzione.

- **Pannello:** apri il menu delle azioni e seleziona **Disable webhook** o **Enable webhook**. La pagina del webhook mostra lo stato **Enabled** o **Disabled**.
- **API:** chiama [Aggiorna un webhook](/it/docs/api-reference/webhooks/update/) con `{"enabled": false}` o `{"enabled": true}`.

Mentre un webhook è disattivato, i nuovi eventi non vengono messi in coda per quel webhook e le richieste già in attesa di un nuovo tentativo vengono messe in pausa. Gli eventi che si verificano mentre è disattivato non vengono consegnati in seguito; se ti servono, leggili con l’[API degli eventi](/it/docs/logs/events/#reconcile-missed-webhook-events). Emailit disattiva anche automaticamente i webhook dopo 3 giorni di errori; vedi [Nuovi tentativi ed errori](/it/docs/webhooks/retries-and-failures/).

Se elimini un webhook, tutti i suoi eventi in attesa vengono scartati.

## Ruota il secret

Ruota il secret se potrebbe essere trapelato, o come normale misura di sicurezza.

- **Pannello:** apri il menu delle azioni, seleziona **Webhook secret**, poi **Reset**. Il nuovo secret viene mostrato una sola volta.
- **API:** chiama [Ruota il secret di firma](/it/docs/api-reference/webhooks/reset-secret/). La risposta contiene il nuovo `secret`. Anche [Recupera un webhook](/it/docs/api-reference/webhooks/get/) restituisce il secret attuale.

Il vecchio secret smette subito di funzionare e ogni richiesta successiva, compresi i nuovi tentativi di eventi precedenti, viene firmata con quello nuovo. Per ruotarlo senza rifiutare richieste, fai accettare al tuo endpoint entrambi i secret per qualche minuto, reimposta il secret, distribuisci il nuovo valore, poi rimuovi quello vecchio.

## Verifica che funzioni

1. Invia un evento di test e conferma che il tuo endpoint restituisce `2xx`.
2. Invia un’email reale, o provoca l’evento che hai sottoscritto.
3. Nella scheda **Requests** del webhook, la richiesta risulta **Delivered**. L’orario **Last used** del webhook si aggiorna.

## Vedi anche

  - [Verifica le firme dei webhook](/it/docs/webhooks/request-signature/)
  - [Richieste webhook](/it/docs/webhooks/webhook-requests/)
  - [Tipi di evento](/it/docs/webhooks/event-types/)
  - [Nuovi tentativi ed errori](/it/docs/webhooks/retries-and-failures/)

---
Fonte: https://emailit.com/it/docs/webhooks/set-up/