> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ricevere l’esito delle operazioni con i webhook

> Registra un endpoint HTTPS, verifica le consegne firmate e recupera quelle fallite.

Le operazioni durevoli, come importazioni, avvii, risposte e modifiche al warmup, terminano in un worker. Un endpoint webhook riceve un evento firmato quando una di queste arriva a un esito, così non devi interrogare `get_api_operation` di continuo. Servono gli scope `webhooks:read` e `webhooks:manage`, un’identità titolare o admin e un host con i webhook attivi. Se non sono attivi, l’host risponde `503 webhooks_unavailable`.

## Registrare un endpoint

Chiama [create\_api\_webhook\_endpoint](https://docs.emailx.ai/it/api-reference/webhooks/create-webhook.md) con un URL `https://` e i tipi di evento che ti interessano. L’URL deve puntare solo a indirizzi internet pubblici: Emailx lo controlla quando lo salvi e prima di ogni consegna, e non segue mai i reindirizzamenti. Il salvataggio non contatta l’URL.

La risposta contiene `secret` una sola volta. Conservalo nel tuo gestore di segreti: Emailx non lo restituisce più. Se lo perdi, [ruota il segreto](https://docs.emailx.ai/it/api-reference/webhooks/rotate-webhook-secret.md).

| Tipo di evento | Inviato quando un’operazione diventa |
| - | - |
| `operation.succeeded` | riuscita |
| `operation.partially_succeeded` | riuscita in parte |
| `operation.failed` | fallita |
| `operation.cancelled` | annullata |
| `operation.needs_reconciliation` | incerta: una persona deve controllare prima di ripetere qualsiasi cosa |
| `operation.awaiting_user_action` | bloccata finché qualcuno non interviene in Emailx |

Gli eventi contengono ID, tipo, stato, codice di errore e risorsa dell’operazione, mai il suo risultato. Per i dettagli usa [get\_api\_operation](https://docs.emailx.ai/it/api-reference/jobs/get-job.md).

## Verificare ogni consegna

Ogni consegna è una `POST` con corpo JSON e tre header:

* `webhook-id`: l’ID dell’evento. Resta lo stesso nei nuovi tentativi e nelle nuove consegne.
* `webhook-timestamp`: i secondi Unix in cui il tentativo è stato firmato.
* `webhook-signature`: uno o più valori `v1,<base64>` separati da spazi.

La firma è un HMAC-SHA256 di `{webhook-id}.{webhook-timestamp}.{corpo grezzo}`, con chiave i byte base64 che seguono `whsec_`. Rifiuta un timestamp che si discosta di oltre cinque minuti dal tuo orologio e accetta la richiesta se almeno un valore `v1` corrisponde.

```python theme={null}
import base64, hashlib, hmac, time

def verify(secret, headers, body: bytes) -> bool:
    ts = int(headers["webhook-timestamp"])
    if abs(time.time() - ts) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f'{headers["webhook-id"]}.{ts}.'.encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(expected, part[3:])
               for part in headers["webhook-signature"].split() if part.startswith("v1,"))
```

Rispondi con un `2xx` entro 10 secondi ed esegui il lavoro dopo. La stessa consegna può arrivare più di una volta: salva `webhook-id` e ignora le ripetizioni.

## Nuovi tentativi e recupero

Un tentativo fallito (risposta diversa da `2xx`, timeout o destinazione non sicura) viene ripetuto dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 8 ore e 24 ore. Dopo sette tentativi la consegna passa a `abandoned`. Dopo 50 tentativi falliti di fila l’endpoint si disattiva da solo con `disabled_reason: too_many_failures`; riattivalo con [update\_api\_webhook\_endpoint](https://docs.emailx.ai/it/api-reference/webhooks/update-webhook.md).

* [Invia un evento di prova](https://docs.emailx.ai/it/api-reference/webhooks/test-webhook.md) per controllare un nuovo endpoint.
* [Elenca le consegne](https://docs.emailx.ai/it/api-reference/webhooks/list-webhook-deliveries.md) per `status` per trovare quelle fallite e [leggine una](https://docs.emailx.ai/it/api-reference/webhooks/get-webhook-delivery.md) per vedere payload ed esito.
* [Consegna di nuovo](https://docs.emailx.ai/it/api-reference/webhooks/redeliver-webhook.md) un evento quando il tuo ricevitore è a posto. Mantiene lo stesso `webhook-id`.
* [Ruota il segreto](https://docs.emailx.ai/it/api-reference/webhooks/rotate-webhook-secret.md) se viene esposto. Il vecchio segreto continua a firmare per 24 ore insieme al nuovo, quindi aggiorna il ricevitore entro quel tempo.

Dalla CLI le stesse azioni sono sotto `emailx webhooks`. Tra gli strumenti MCP ci sono `create_webhook_endpoint`, `send_webhook_test`, `list_webhook_deliveries` e `redeliver_webhook`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.