Formular-ID

Webhooks

Webhook-Events und Payloads, Prüfung der HMAC-SHA256-Signatur, Reihenfolge, erneute Versuche, Schutz für Endpunkte, Replay und eigene Header.

Webhooks schicken Events zu Einsendungen an deinen Server, sobald sie passieren: neue Einsendungen, Verschiebungen in den Spam und zurück sowie Löschungen. Zustellungen werden nach dem Standard Webhooks-Schema signiert, etwa drei Tage lang erneut versucht und im Dashboard Versuch für Versuch protokolliert. Fertige Handler findest du unter Webhooks empfangen.

Für Slack, Discord, Telegram, Google Sheets, Notion, Airtable, HubSpot, Attio oder Pipedrive brauchst du keinen Webhook: Füge dem Formular stattdessen eine Integration hinzu.

Füge einen Endpunkt hinzu

  1. Öffne im Dashboard Webhooks und wähle Add endpoint.
  2. Gib eine HTTPS-URL ein und wähle ein Formular oder alle Formulare im Workspace.
  3. Wähle die Events, die er empfängt. Ein neuer Endpunkt empfängt nur submission.created.
  4. Kopiere das Signatur-Secret. Es beginnt mit whsec_ und wird nur einmal vollständig angezeigt.
  5. Sende ein Test-Event, um deinen Handler zu prüfen.

Du kannst Endpunkte auch mit der REST API oder einem KI-Agenten, der mit dem MCP-Server verbunden ist, hinzufügen, ändern, deaktivieren und löschen. Das Secret wird auch dort einmalig zurückgegeben.

Endpunkt-URLs

  • Nur https:, auf dem Standardport 443, ohne Benutzername oder Passwort in der URL, bis zu 2.048 Zeichen.
  • Ein öffentlicher Hostname. IP-Adressen, localhost und Namen, die auf .local, .internal, .intranet, .lan, .home.arpa oder .onion enden, werden abgelehnt, ebenso ikiform.com, workers.dev und pages.dev.
  • Der Hostname darf nur zu öffentlichen Adressen auflösen. Private, Loopback-, Link-Local- und Carrier-Grade-NAT-Bereiche werden abgelehnt.
  • Die URL wird beim Speichern und erneut vor jeder Zustellung geprüft. Ein Endpunkt, der plötzlich zu einer privaten Adresse auflöst, wird deaktiviert.
  • Ein Workspace kann bis zu 3 Endpunkte haben. Enterprise hat kein Limit.

Events

Jeder Endpunkt empfängt nur die Events, die er abonniert hat. Ändere sie jederzeit mit Edit am Endpunkt.

TypGesendet, wennStandardmäßig abonniert
submission.createdEine Einsendung empfangen wird oder eine Spam-Einsendung als kein Spam markiert wirdJa
submission.updatedEine Einsendung im Dashboard oder über die REST API von empfangen nach Spam verschoben wird oder zurückNein
submission.deletedEine Einsendung im Dashboard oder über die REST API gelöscht wirdNein
submission.spamEine neue Einsendung als Spam gespeichert wirdNein
endpoint.testDu auf der Endpunkt-Seite Send test wählst. Einmal gesendet, ohne erneute VersucheImmer
  • Spam löst nichts aus, außer der Endpunkt hat submission.spam abonniert. Einsendungen, die zurückgehalten werden, weil der Workspace über seinem Limit liegt, lösen nichts aus, bis sie freigegeben werden, und senden dann submission.created.
  • Eine Einsendung als kein Spam zu markieren sendet submission.updated und außerdem submission.created an jeden Endpunkt, der es abonniert hat und für diese Einsendung noch keins erhalten hat.
  • Eine Einsendung als Spam zu markieren sendet submission.updated und bricht ihre submission.created-Zustellungen ab, die noch nicht verschickt wurden.
  • Eine Einsendung zu löschen entfernt ihre früheren Zustellungen und sendet submission.deleted, das nur IDs enthält, nie Feldwerte.

Der Request

Jede Zustellung ist ein POST mit einem JSON-Body und drei Signatur-Headern, gesendet vom Zustelldienst von Ikiform mit dem User-Agent Ikiform-Webhooks/1.0.

Header
POST /webhooks/ikiform HTTP/1.1
content-type: application/json
user-agent: Ikiform-Webhooks/1.0
webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
HeaderWert
webhook-idDie Zustellungs-ID. Bei jedem erneuten Versuch derselben Zustellung gleich, nutze sie also, um Duplikate zu ignorieren
webhook-timestampUnix-Sekunden, zu denen dieser Versuch signiert wurde. Bei jedem Versuch neu
webhook-signaturev1, plus ein Base64-HMAC-SHA256. Mehrere durch Leerzeichen getrennte Werte, während ein Secret rotiert wird

Payloads

Jedes Event hat denselben Rahmen: id, type, timestamp, api_version und data. Das data jedes Typs:

{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-17T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "sequence": 17922384000000,
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-17T12:00:00.000Z",
    "truncated": false
  }
}
FeldBeschreibung
idDie Zustellungs-ID, gleich wie webhook-id
typeDer Event-Typ
timestampWann die Zustellung erstellt wurde, in ISO 8601 UTC. Bei jedem erneuten Versuch gleich
api_versionDie Payload-Version, mit der der Endpunkt erstellt wurde, derzeit 2026-10-17
data.submission_idDie ID der Einsendung. Rufe sie mit der REST API ab
data.sequenceEine Zahl, die mit jeder Änderung an der Einsendung wächst. Nutze sie, um Zustellungen wieder in die richtige Reihenfolge zu bringen
data.formid und name des Formulars
data.fieldsDie gespeicherten Werte. Wenn Felder definiert sind, sind das die validierten, umgewandelten Werte
data.metaDieselben Schlüssel wie meta in der REST API. Jeder Schlüssel ist vorhanden, und jeder Wert kann null sein. Die IP des Besuchers und ihr Hash werden nie gesendet
data.meta.user_agentDer User-Agent des Browsers, bis zu 512 Zeichen
data.meta.origin, referrerWoher der Post kam, sofern der Browser sie gesendet hat
data.meta.countryZweibuchstabiger Ländercode, von Cloudflare
data.meta.subject, reply_toAus den Feldern _subject und _replyto
data.created_atWann die Einsendung gespeichert wurde
data.truncatedtrue, wenn der Body über 256 KB groß wäre; in diesem Fall ist fields leer
data.status, previous_statusBei submission.updated: der neue und der alte Status, received oder spam. Bei submission.spam: immer spam
data.spamBei submission.spam: der Spam-score und seine reasons, etwa honeypot oder keyword
data.deleted_atBei submission.deleted, das weder fields noch meta oder created_at hat

Jeder meta-Wert kann null sein. Behandle Feldwerte als nicht vertrauenswürdige Eingaben, genau wie einen Formular-Post an deinen eigenen Server.

Reihenfolge und Duplikate

Es ist nicht garantiert, dass Zustellungen in der richtigen Reihenfolge ankommen. Ein erneuter Versuch kann nach einem neueren Event eintreffen, und ein langsamer Endpunkt kann ein submission.updated vor dem submission.created sehen, auf das es folgt. Zwei Werte machen das sicher:

WertWofür
webhook-idDuplikate ignorieren. Sie ist bei jedem erneuten Versuch und bei einem Replay gleich und dient deshalb als Idempotenzschlüssel
data.sequenceEvents einer Einsendung ordnen. Speichere pro submission_id den höchsten Wert, den du angewendet hast, und überspringe jede Zustellung mit einer kleineren oder gleichen Zahl
app/api/webhooks/ikiform/route.ts
import { verifyWebhook } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const event = await verifyWebhook({
    payload: await request.text(),
    headers: request.headers,
    secret: process.env.IKIFORM_WEBHOOK_SECRET!,
  });
  if (event.type === "endpoint.test") return new Response(null, { status: 204 });

  const status =
    event.type === "submission.deleted"
      ? "deleted"
      : event.type === "submission.created"
        ? "received"
        : event.data.status;

  await db.query(
    `insert into leads (submission_id, sequence, status, delivery_id)
     values ($1, $2, $3, $4)
     on conflict (submission_id) do update
       set sequence = excluded.sequence, status = excluded.status, delivery_id = excluded.delivery_id
       where leads.sequence < excluded.sequence`,
    [event.data.submission_id, event.data.sequence, status, event.id],
  );
  return new Response(null, { status: 204 });
}

Die where-Klausel wendet eine Zustellung nur an, wenn sie neuer ist als der gespeicherte Stand. So kann ein verspätetes submission.created keine gelöschte Einsendung zurückholen, und ein erneuter Versuch einer bereits angewendeten Zustellung ändert nichts.

Eigene Header

Füge unter Headers beim Anlegen oder Bearbeiten eines Endpunkts bis zu 10 feste Header hinzu, zum Beispiel einen Authorization-Header, den Zapier, n8n oder dein eigenes Gateway erwartet. Sie werden mit jeder Zustellung an diesen Endpunkt gesendet, Tests eingeschlossen.

Header
POST /hooks/catch/123456/abcdef HTTP/1.1
content-type: application/json
user-agent: Ikiform-Webhooks/1.0
authorization: Bearer zap_live_…
x-source: ikiform
webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
  • Namen bestehen aus Buchstaben, Ziffern und Bindestrichen, bis zu 64 Zeichen. Werte sind druckbares ASCII in einer Zeile, bis zu 1.024 Zeichen.
  • Werte werden verschlüsselt gespeichert und nie wieder angezeigt. Der Endpunkt und sein Zustellungsprotokoll zeigen nur die Namen. Namen werden im Klartext gespeichert, also gehören Geheimnisse nur in Werte, nie in Namen. Lass einen gespeicherten Wert leer, um ihn zu behalten, oder gib einen neuen ein, um ihn zu ersetzen.
  • Header, die Ikiform selbst setzt oder die die Verbindung steuern, werden abgelehnt: content-type, content-length, user-agent, host, cookie und ähnliche sowie jeder Name, der mit webhook-, cf-, x-forwarded-, proxy- oder sec- beginnt. Die eigenen Header von Ikiform haben immer Vorrang.
  • Eigene Header sind nicht durch die Signatur abgedeckt. Ein geteiltes Token beweist weniger als eine Signatur, prüfe also auch webhook-signature, wann immer dein Empfänger das kann.

Prüfe die Signatur

Wie die Webhook-Signatur berechnet wird
webhook-id.webhook-timestamp.roher Body

HMAC-SHA256, mit dem base64-dekodierten Secret nach whsec_ als Schlüssel

webhook-signature: v1,base64(signature)

  • Verwende den rohen Request-Body genau so, wie er empfangen wurde. Parsen und erneutes Serialisieren von JSON verändert die Bytes.
  • Der Header kann mehrere durch Leerzeichen getrennte Signaturen enthalten. Akzeptiere den Request, wenn irgendeine v1-Signatur passt.
  • Vergleiche in konstanter Zeit und lehne Zeitstempel ab, die mehr als 5 Minuten von jetzt abweichen.

Mit dem SDK

verifyWebhook erledigt all das mit Web Crypto und gibt das geparste Event zurück oder wirft WebhookVerificationError mit einem reason. Es akzeptiert ein Headers-Objekt oder ein einfaches Record wie req.headers in Node.

app/api/webhooks/ikiform/route.ts
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    if (event.type === "submission.created") {
      console.log(event.data.fields);
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(error.reason, { status: 400 });
    }
    throw error;
  }
}

Ohne das SDK

Jede Standard-Webhooks-Bibliothek funktioniert ebenfalls. Von Hand sind es nur ein paar Zeilen:

import { createHmac, timingSafeEqual } from "node:crypto";

const secret = Buffer.from(process.env.IKIFORM_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

export function verify(body, headers) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${id}.${timestamp}.${body}`).digest();
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Signaturprüfer

5-Minuten-Fenster ignorieren

Nutzt verifyWebhook aus dem SDK mit Web Crypto in deinem Browser. Nichts, was du einfügst, verlässt diese Seite.

Antworten

Deine AntwortWas Ikiform macht
Ein beliebiger 2xx innerhalb von 15 SekundenMarkiert die Zustellung als erfolgreich
410 GoneLässt die Zustellung fehlschlagen und deaktiviert den Endpunkt sofort
429 oder 503 mit Retry-AfterVersucht es nach dieser Verzögerung erneut, aber nicht später als beim nächsten Schritt im Zeitplan
Eine WeiterleitungWird nicht befolgt. Zählt als Fehlschlag
Jeder andere Status, ein Timeout oder ein NetzwerkfehlerErneute Versuche nach dem Zeitplan unten

Erledige langsame Arbeit nach dem Antworten, zum Beispiel in einer Queue. Die ersten 4 KB deines Response-Bodys werden im Zustellungsprotokoll gespeichert.

Erneute Versuche

Ein fehlgeschlagener Versuch wird nach diesem Zeitplan erneut versucht, jede Verzögerung mit bis zu 20 % zufälligem Jitter in beide Richtungen. Nach dem 9. Versuch, etwa 3 Tage und 6 Stunden nach dem ersten, wird die Zustellung als fehlgeschlagen markiert.

Zeitplan für Webhook-Wiederholungen, mit der Wartezeit vor jedem Versuch auf einer logarithmischen Skala
VersuchWartezeit davorSeit dem ersten
  1. 1jetzt0 s
  2. 25 s5 s
  3. 35 min5 min
  4. 430 min35 min
  5. 52 h2 h 35 min
  6. 65 h7 h 35 min
  7. 710 h17 h 35 min
  8. 81 T1 T 18 h
  9. 91 T 12 h3 T 6 h

Dunkle Balken zeigen die kürzeste Wartezeit und helle die längste, bei 20 % Jitter in beide Richtungen. Nach Versuch 9 wird die Zustellung als fehlgeschlagen markiert.

Schutz für Endpunkte

Wenn ein Endpunkt Probleme hat, bremst Ikiform ab, statt noch mehr zu schicken, und sagt dir, wenn er ausfällt oder wieder da ist.

SchutzmaßnahmeWas passiert
ParallelitätHöchstens 5 Requests laufen gleichzeitig an einen Endpunkt. Der Rest wartet, bis er dran ist
PauseNach 20 fehlgeschlagenen Versuchen in Folge pausieren Zustellungen an den Endpunkt für 5 Minuten. Jede weitere Pause in Folge verdoppelt sich, bis zu 1 Stunde. Ein Erfolg beendet sie
DeaktivierungNach 5 Tagen ohne erfolgreiche Zustellung wird der Endpunkt deaktiviert, und die Benachrichtigungsadresse des Workspace oder seine Inhaber bekommen eine E-Mail
WiederhergestelltWenn ein Endpunkt, der eine Stunde oder länger fehlgeschlagen ist, wieder Erfolg hat, bekommt dieselbe Adresse eine E-Mail, dass er wieder funktioniert
  • Auf einen freien Platz oder das Ende einer Pause zu warten verbraucht keinen Versuch. Die Zustellung behält alle ihre erneuten Versuche.
  • Erneute Versuche, die du von Hand startest, und Test-Events überspringen die Pause, damit du eine Korrektur sofort prüfen kannst.
  • Die Endpunkt-Seite zeigt eine Zeile, wenn Zustellungen pausiert sind, wenn dein Server sie mit 4xx ablehnt oder wenn sie fehlschlagen.

Deaktivierte Endpunkte

Eine 410 Gone-Antwort oder ein Ziel, das privat wird, deaktiviert einen Endpunkt sofort, ebenso 5 Tage mit Fehlern. Ein deaktivierter Endpunkt empfängt nichts: Neue Events werden für ihn nicht eingereiht, und wartende Zustellungen schlagen fehl. Schalte ihn mit Enabled auf der Endpunkt-Seite wieder ein, sobald er repariert ist. Ikiform bietet dann an, die Zustellungen erneut zu senden, die seit Beginn der Fehler fehlgeschlagen sind, bis zu 7 Tage zurück.

Fehlgeschlagene Zustellungen erneut senden

Wähle Replay failed deliveries im Menü des Endpunkts und dann die letzten 24 Stunden, 3 Tage oder 7 Tage. Jede in diesem Zeitraum erstellte Zustellung, die fehlgeschlagen ist oder abgebrochen wurde, wird innerhalb etwa einer Minute erneut gesendet, bis zu 1.000 auf einmal. Ist der Endpunkt pausiert, warten Replays, bis die Pause endet. Replays behalten ihre ursprüngliche webhook-id und sequence, deine Prüfungen auf Duplikate und Reihenfolge greifen also weiterhin.

  • Eine Zustellung, die alle Versuche verbraucht hatte, bekommt einen weiteren. Eine, die früher gestoppt wurde, etwa weil der Endpunkt deaktiviert war, setzt ihren Zeitplan für erneute Versuche fort.
  • Zustellungen für ein gelöschtes Formular werden übersprungen, ebenso Events, die nicht mehr zu ihrer Einsendung passen: eine, die gelöscht wurde, oder ein submission.created für eine Einsendung, die jetzt Spam ist.
  • Jeder Retry und jedes Replay sendet genau den Body des ersten Versuchs, Byte für Byte, auch wenn sich Submission, Formularname oder API-Version inzwischen geändert haben. Nur webhook-timestamp und webhook-signature sind neu und frisch signiert, damit deine Prüfung besteht.
  • Der Endpunkt muss aktiviert sein. Test-Events werden nie erneut gesendet.

Zustellungsprotokolle

Jede Endpunkt-Seite listet ihre Zustellungen mit ihrem Status auf. Klapp eine auf, um jeden Versuch zu sehen: wann er lief, ob er automatisch, manuell oder ein Test war, den Statuscode, die Dauer und die ersten 4 KB deiner Antwort oder den Fehler. Von dort kannst du jede Zustellung erneut senden. Versuche werden 30 Tage und Zustellungen 90 Tage lang aufbewahrt.

Secrets rotieren

Signing-Secret erneuern, oder POST /webhooks/:endpointId/roll-secret, erstellt ein neues Secret. In den nächsten 24 Stunden wird jede Zustellung mit dem alten und dem neuen Secret signiert, sodass webhook-signature zwei Werte enthält und du das neue Secret bereitstellen kannst, ohne Ereignisse zu verlieren.