Webhooks

Verfügbar in den Tarifen: Professional, Business

Mit Formspree kannst du einen Webhook konfigurieren, der jedes Mal ausgelöst wird, wenn ein Formular eine neue Übermittlung erhält. Webhooks können mit serverlosen Funktionen, eigenem Server-Code oder anderen Drittanbieter-Diensten verwendet werden, um eine benutzerdefinierte Verarbeitung von Formularübermittlungen durchzuführen.

Serverlose Funktionen bieten eine leichtgewichtige Möglichkeit, Formularübermittlungen zu verarbeiten. Anstatt einen vollständigen Webserver nur zum Verarbeiten von Formularübermittlungen zu erstellen, kannst du eine einzelne serverlose Funktion erstellen und auf einer serverlosen Plattform bereitstellen. Es gibt mehrere Plattformen zum Hosten von Funktionen, wie Cloudflare Workers, AWS Lambda und Google Cloud Functions. Das Beispiel unten verwendet Cloudflare Workers, die einen großzügigen kostenlosen Tarif und einen schnellen Weg vom Code zu einem bereitgestellten Endpoint bieten.

Wenn du dein Webhook-Plugin aktivierst, wirst du aufgefordert, einen Webhook-Typ auszuwählen, entweder Simple Webhook, Build Hook oder REST Hook.

Simple Webhooks

Das sind normale Webhooks. Wir senden die Payload einfach als POST-Anfragen an die gewünschte URL, ohne Fragen zu stellen.

Build Hooks

Das sind Hooks, die verwendet werden können, um neue Builds bei Drittanbieter-Diensten wie Netlify auszulösen. Das ist im Grunde ein Webhook mit einem leeren Body.

REST Hooks

Falls du es brauchst, senden wir auch Webhooks, die dem REST Hooks-Protokoll entsprechen. Das wird von einigen Diensten unterstützt und beinhaltet einen Handshake im Moment der Erstellung des Webhooks.

Den Resthook-Handshake verarbeiten

Wenn du das Resthook-Protokoll wählst, sendet Formspree, bevor es beginnt, Webhook-Anfragen zu senden, eine Bestätigungsanfrage mit einem X-Hook-Secret-Header. Weitere Informationen zum Resthook-Handshake findest du in den Resthooks-Docs zum Thema Sicherheit.

Hier ist ein Beispiel dafür, wie du den Resthook-Handshake in einem Cloudflare Worker verarbeitest, wobei dieselben Konzepte gelten, wenn du es in deinem eigenen Webserver implementierst.

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 });
  },
};

In Schritt 1 oben antwortet der Worker auf den ursprünglichen Resthook-Handshake mit einer Antwort, die den x-hook-secret-Header aus der Anfrage zurückspiegelt. Der Body ist leer.

Schritt 2 ist die Stelle, an der deine benutzerdefinierte Funktionalität steht. Cloudflare Workers laufen auf einem V8-Isolate mit der standardmäßigen fetch-API sowie Bindings für KV, R2, D1 und Queues – du kannst Übermittlungen persistieren, sie an einen anderen Dienst weiterleiten oder von hier aus jede nachgelagerte Aktion auslösen. Details zu Bereitstellung und Bindings findest du in den Cloudflare-Workers-Docs.

Webhooks-Payload

Bei jeder neu eingegangenen Übermittlung wird ein Webhook gesendet.

Mit Ausnahme von Buildhooks (die leer sind) hat die Payload der Webhooks die folgende Struktur:

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