Webhook

Un webhook è una chiamata HTTP che Sofia scatena quando un post è online o fallisce. Usalo per riprendere il contenuto in un foglio di calcolo, avvisare uno strumento di messaggistica o lanciare uno scenario in Zapier o n8n.

Aggiungerne uno

• 1. Dagli un indirizzo. Un indirizzo https pubblico a cui Sofia invierà l’evento.
• 2. Scegli gli eventi. post.published e post.failed.
• 3. Registralo. POST /v1/webhooks: il segreto di firma (whsec_…) viene mostrato solo in questa risposta.
• 4. Invia un test. POST /v1/webhooks/{id}/test invia un evento webhook.test, firmato come gli altri.

La richiesta completa è dettagliata nella scheda API: Registrare un webhook. Vengono annunciati solo i post creati dalla tua applicazione.

Costruire il ricevitore

Invia sempre prima un test e conserva il corpo ricevuto: è il contratto, più affidabile di qualsiasi descrizione. Sofia invia ogni evento in POST nel formato JSON { id, type, createdAt, data }, con gli header Sofia-Event-Id, Sofia-Event-Type e Sofia-Signature.

• Verifica la firma. Sofia-Signature vale t=<unix time>,v1=<hex>, dove v1 è l’HMAC-SHA256 di <t>.<raw body> con il tuo segreto. Calcolalo sul corpo grezzo e rifiuta un timestamp vecchio.
• Rispondi `2xx` in fretta, poi fai il lavoro dopo: un endpoint lento non si distingue da un endpoint fuori uso.
• Sii idempotente. Lo stesso evento può arrivare due volte: deduplica su Sofia-Event-Id.

Quando un webhook non scatta più

L’indirizzo non è raggiungibile

Sofia chiama dai suoi server: l’indirizzo deve essere un https pubblico. Un reindirizzamento non viene mai seguito, e 10 secondi senza risposta contano come un fallimento.

L’indirizzo restituisce un errore

Qualsiasi risposta diversa da 2xx fa scattare un nuovo tentativo dopo 1 minuto, 5 minuti, 30 minuti e 2 ore, fino a 5 tentativi. Guarda prima i tuoi log, poi riproduci con POST /v1/webhooks/{id}/test.

Il post non è stato creato dalla tua applicazione

Un webhook annuncia solo i post creati dalla tua applicazione; un post creato nell’interfaccia non lo fa scattare.

Da leggere anche

Un webhook dice quando Sofia ha agito. Per far agire Sofia, usa Sofia API, la CLI sofia o il server MCP (schede API e Agents), oppure Integrazioni di terze parti.