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
- Öffne im Dashboard Webhooks und wähle Add endpoint.
- Gib eine HTTPS-URL ein und wähle ein Formular oder alle Formulare im Workspace.
- Wähle die Events, die er empfängt. Ein neuer Endpunkt empfängt nur
submission.created. - Kopiere das Signatur-Secret. Es beginnt mit
whsec_und wird nur einmal vollständig angezeigt. - 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,
localhostund Namen, die auf.local,.internal,.intranet,.lan,.home.arpaoder.onionenden, 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.
| Typ | Gesendet, wenn | Standardmäßig abonniert |
|---|---|---|
submission.created | Eine Einsendung empfangen wird oder eine Spam-Einsendung als kein Spam markiert wird | Ja |
submission.updated | Eine Einsendung im Dashboard oder über die REST API von empfangen nach Spam verschoben wird oder zurück | Nein |
submission.deleted | Eine Einsendung im Dashboard oder über die REST API gelöscht wird | Nein |
submission.spam | Eine neue Einsendung als Spam gespeichert wird | Nein |
endpoint.test | Du auf der Endpunkt-Seite Send test wählst. Einmal gesendet, ohne erneute Versuche | Immer |
- Spam löst nichts aus, außer der Endpunkt hat
submission.spamabonniert. Einsendungen, die zurückgehalten werden, weil der Workspace über seinem Limit liegt, lösen nichts aus, bis sie freigegeben werden, und senden dannsubmission.created. - Eine Einsendung als kein Spam zu markieren sendet
submission.updatedund außerdemsubmission.createdan jeden Endpunkt, der es abonniert hat und für diese Einsendung noch keins erhalten hat. - Eine Einsendung als Spam zu markieren sendet
submission.updatedund bricht ihresubmission.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.
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=| Header | Wert |
|---|---|
webhook-id | Die Zustellungs-ID. Bei jedem erneuten Versuch derselben Zustellung gleich, nutze sie also, um Duplikate zu ignorieren |
webhook-timestamp | Unix-Sekunden, zu denen dieser Versuch signiert wurde. Bei jedem Versuch neu |
webhook-signature | v1, 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
}
}| Feld | Beschreibung |
|---|---|
id | Die Zustellungs-ID, gleich wie webhook-id |
type | Der Event-Typ |
timestamp | Wann die Zustellung erstellt wurde, in ISO 8601 UTC. Bei jedem erneuten Versuch gleich |
api_version | Die Payload-Version, mit der der Endpunkt erstellt wurde, derzeit 2026-10-17 |
data.submission_id | Die ID der Einsendung. Rufe sie mit der REST API ab |
data.sequence | Eine Zahl, die mit jeder Änderung an der Einsendung wächst. Nutze sie, um Zustellungen wieder in die richtige Reihenfolge zu bringen |
data.form | id und name des Formulars |
data.fields | Die gespeicherten Werte. Wenn Felder definiert sind, sind das die validierten, umgewandelten Werte |
data.meta | Dieselben 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_agent | Der User-Agent des Browsers, bis zu 512 Zeichen |
data.meta.origin, referrer | Woher der Post kam, sofern der Browser sie gesendet hat |
data.meta.country | Zweibuchstabiger Ländercode, von Cloudflare |
data.meta.subject, reply_to | Aus den Feldern _subject und _replyto |
data.created_at | Wann die Einsendung gespeichert wurde |
data.truncated | true, wenn der Body über 256 KB groß wäre; in diesem Fall ist fields leer |
data.status, previous_status | Bei submission.updated: der neue und der alte Status, received oder spam. Bei submission.spam: immer spam |
data.spam | Bei submission.spam: der Spam-score und seine reasons, etwa honeypot oder keyword |
data.deleted_at | Bei 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:
| Wert | Wofür |
|---|---|
webhook-id | Duplikate ignorieren. Sie ist bei jedem erneuten Versuch und bei einem Replay gleich und dient deshalb als Idempotenzschlüssel |
data.sequence | Events 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 |
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.
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,cookieund ähnliche sowie jeder Name, der mitwebhook-,cf-,x-forwarded-,proxy-odersec-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
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.
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
Nutzt verifyWebhook aus dem SDK mit Web Crypto in deinem Browser. Nichts, was du einfügst, verlässt diese Seite.
Antworten
| Deine Antwort | Was Ikiform macht |
|---|---|
Ein beliebiger 2xx innerhalb von 15 Sekunden | Markiert die Zustellung als erfolgreich |
410 Gone | Lässt die Zustellung fehlschlagen und deaktiviert den Endpunkt sofort |
429 oder 503 mit Retry-After | Versucht es nach dieser Verzögerung erneut, aber nicht später als beim nächsten Schritt im Zeitplan |
| Eine Weiterleitung | Wird nicht befolgt. Zählt als Fehlschlag |
| Jeder andere Status, ein Timeout oder ein Netzwerkfehler | Erneute 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.
- 1jetzt0 s
- 25 s5 s
- 35 min5 min
- 430 min35 min
- 52 h2 h 35 min
- 65 h7 h 35 min
- 710 h17 h 35 min
- 81 T1 T 18 h
- 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ßnahme | Was passiert |
|---|---|
| Parallelität | Höchstens 5 Requests laufen gleichzeitig an einen Endpunkt. Der Rest wartet, bis er dran ist |
| Pause | Nach 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 |
| Deaktivierung | Nach 5 Tagen ohne erfolgreiche Zustellung wird der Endpunkt deaktiviert, und die Benachrichtigungsadresse des Workspace oder seine Inhaber bekommen eine E-Mail |
| Wiederhergestellt | Wenn 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
4xxablehnt 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.createdfü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-timestampundwebhook-signaturesind 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.