Ricevere l’esito delle operazioni con i webhook

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 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.

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.

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.

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.

Invia un evento di prova per controllare un nuovo endpoint.
Elenca le consegne per status per trovare quelle fallite e leggine una per vedere payload ed esito.
Consegna di nuovo un evento quando il tuo ricevitore è a posto. Mantiene lo stesso webhook-id.
Ruota il segreto 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.

Get started

Sending well

Build a workflow

Ricevere l’esito delle operazioni con i webhook

Registrare un endpoint

Verificare ogni consegna

Nuovi tentativi e recupero

​Registrare un endpoint

​Verificare ogni consegna

​Nuovi tentativi e recupero

Registrare un endpoint

Verificare ogni consegna

Nuovi tentativi e recupero