Webhook

Disponibile sui piani: Professional, Business

Formspree ti consente di configurare un webhook che verrà attivato ogni volta che un modulo riceve un nuovo invio. I webhook possono essere usati con funzioni serverless, codice server personalizzato o altri servizi di terze parti, per eseguire una gestione personalizzata degli invii del modulo.

Le funzioni serverless forniscono un modo leggero per elaborare gli invii del modulo. Invece di creare un server web completo solo per elaborare gli invii del modulo, puoi creare una singola funzione serverless e distribuirla su una piattaforma serverless. Esistono diverse piattaforme per l’hosting di funzioni, come Cloudflare Workers, AWS Lambda e Google Cloud Functions. L’esempio qui sotto usa Cloudflare Workers, che offre un generoso piano gratuito e un percorso rapido dal codice a un endpoint distribuito.

Quando abiliti il tuo plugin Webhook ti verrà chiesto di selezionare un tipo di webhook, tra Simple Webhook, Build Hook o REST Hook.

Simple Webhook

Questi sono webhook normali. Invieremo semplicemente il payload all’URL desiderato come richieste POST senza fare domande.

Build Hook

Questi sono hook che possono essere usati per attivare nuove build su servizi di terze parti come Netlify. Questo è fondamentalmente un webhook con un corpo vuoto.

REST Hook

Nel caso ne avessi bisogno, inviamo anche webhook che aderiscono al protocollo REST Hooks. Questo è supportato da alcuni servizi e prevede un handshake nel momento in cui il webhook viene creato.

Gestire l’handshake di Resthook

Quando scegli il protocollo Resthook, prima che Formspree inizi a inviare richieste webhook, invierà una richiesta di conferma con un header X-Hook-Secret. Vedi la documentazione di resthooks sulla sicurezza per maggiori informazioni sull’handshake di resthook.

Ecco un esempio di come gestire l’handshake di resthook in un Cloudflare Worker, anche se gli stessi concetti si applicano se stai implementando nel tuo server web.

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname !== '/hook') {
      return new Response(url.pathname + '\n');
    }

    const hookSecret = request.headers.get('x-hook-secret');
    if (hookSecret) {
      // Step 1: Confirm the subscription. This request includes an
      // X-Hook-Secret header, and we echo it back to complete the
      // handshake.
      return new Response(null, {
        headers: { 'x-hook-secret': hookSecret },
      });
    }

    // Step 2: Receive webhook requests — do something with the payload!
    const payload = await request.json();
    console.log('Received webhook!', payload);
    return new Response(null, { status: 200 });
  },
};

Nel Passaggio 1 sopra, il Worker risponde all’handshake iniziale di resthook con una risposta che restituisce l’header x-hook-secret della richiesta. Il corpo è vuoto.

Il Passaggio 2 è dove va la tua funzionalità personalizzata. I Cloudflare Workers vengono eseguiti su un isolate V8 con l’API standard fetch più i binding per KV, R2, D1 e le code — puoi persistere gli invii, inoltrarli a un altro servizio o attivare qualsiasi azione a valle da qui. Consulta la documentazione di Cloudflare Workers per i dettagli sul deployment e sui binding.

Payload dei webhook

Un webhook viene inviato a ogni nuovo invio ricevuto.

Eccetto per i Buildhook (che sono vuoti), il payload dei webhook ha la seguente struttura:

{
  "form": "",
  "keys": ["keys", "in", "the", "order", "they", "were", "submitted"],
  "submission": {
    "_date": "2029-12-31T00:00:00",
    "field": "value",
    "other-fields": "other value"
  }
}