Aangepaste webhooks

Hoe het werkt

Bij elke inzending stuurt formbase een JSON-body via POST naar je webhook-URL. Het verzoek is ondertekend met HMAC-SHA256, wordt bij een fout opnieuw geprobeerd en wordt vastgelegd in het gebeurtenislogboek van de integratie. Deze pagina behandelt het instellen. De exacte payload, headers en het handtekeningalgoritme staan in de webhookreferentie.

Een webhook toevoegen

1. 1

   Open de integraties van het formulier

   Formulier → Instellingen → Integraties → Webhook.

2. 2

   URL

   Typ de host en het pad — de https://-prefix ligt vast in het invoerveld. Gewoon http:// wordt alleen geaccepteerd voor localhost tijdens ontwikkeling.

3. 3

   Koppeling

   Laat het leeg om elk veld te sturen. Voeg rijen toe om alleen die velden te sturen, onder de JSON-sleutel die je kiest. De koppeling vormt answers en display samen, dus een hernoemde sleutel is in allebei hernoemd. Het volledige verzoek onder de koppeling wordt bijgewerkt terwijl je die bewerkt.

4. 4

   Headers

   Er wordt een ondertekeningsgeheim voor je aangemaakt dat begint met whsec_. Dit kan na het aanmaken niet worden gewijzigd. Voeg in dezelfde stap tot 5 aangepaste headers toe die je eindpunt nodig heeft, zoals een autorisatietoken, en zet Stuur de veldlijst met elk event aan als je ontvanger fields.list niet kan aanroepen. Content-Type wordt automatisch ingesteld en kan niet worden overschreven.

5. 5

   Afronden

   Klik op Stuur een test-event om een gesynthetiseerde voorbeeldinzending te POSTen, en klik daarna op Maak integratie.

Welke URL’s formbase accepteert

• https:// overal, of http:// voor localhost en *.localhost tijdens ontwikkeling.

• Geen inloggegevens in de URL, en maximaal 2.048 tekens.

• Geen privé- of interne adressen. De hostnaam wordt opgelost en direct vóór elke levering opnieuw gecontroleerd, zodat een DNS-record dat na het instellen naar een intern adres wijst, alsnog wordt geweigerd.

Een geweigerde URL is een configuratieprobleem, geen tijdelijk probleem: de levering mislukt permanent in plaats van opnieuw te worden geprobeerd.

Wat je ontvangt

Elk verzoek is dezelfde event-envelop — id, type, createdAt, apiVersion, test en data. In data staan het formulier, de inzending (id, e-mailadres van de respondent, tijdstip van indiening, PDF-link, taal), een answers-object met de veldsleutel als key, en een display-object met dezelfde keys als leesbare tekst. Elk antwoord verschijnt één keer, in elke map.

Zie de referentie voor de volledige payloadvorm, answers en display, en hoe een herhalende groep wordt weergegeven.

Om de exacte body voor je formulier te bekijken, open je de integratie en vouw je Voorbeeldpayload open onder het ondertekeningsgeheim. Deze toont je huidige koppeling met voorbeeldantwoorden.

Handtekeningen verifiëren

Elk verzoek bevat een X-formbase-Signature-header: t=TIMESTAMP,sha256=HEX, een HMAC-SHA256 van TIMESTAMP.BODY berekend met je ondertekeningsgeheim. Het geheim zelf wordt nooit verstuurd. De referentie bevat een kant-en-klaar verificatiefragment.

Verlaten reactie-events

Aangepaste webhooks worden alleen geactiveerd voor voltooide inzendingen en bewerkingen — nooit voor verlaten concepten. Een aangepaste webhook is de enige ontvanger die beide krijgt: een Zapier-, Make- of n8n-abonnement kiest eerste inzendingen of bewerkingen, nooit allebei. Gebruik voor verlaten concepten een provider met een stap Verlaten inzendingen: Google Sheets, Airtable, Notion, Slack, Discord, Linear of GitHub Issues. Elk daarvan heeft zijn eigen inactiviteitsvenster en, waar van toepassing, zijn eigen berichttemplate. Die stap vereist Pro of Business.

Nieuwe pogingen en mislukkingen

• Een levering slaagt bij elke 2xx.

• Tot 5 pogingen: de eerste wordt direct verstuurd, nieuwe pogingen wachten minstens 1, 2, 4 en 8 minuten. formbase zoekt elke 30 minuten naar nieuwe pogingen die klaarstaan, dus de laatste poging komt zo’n twee uur na de eerste. Een Retry-After-header bij een 429 of 5xx wordt gerespecteerd wanneer die om een langere wachttijd vraagt.

• 429, 5xx, timeouts en verbindingsfouten worden opnieuw geprobeerd. Elke andere 4xx mislukt direct.

• Na 5 opeenvolgende mislukkingen pauzeert de integratie automatisch en ontvangt de persoon die haar heeft ingesteld een e-mail. Los het eindpunt op en klik daarna op Hervat.

• 401, 403 en 404 stoppen de integratie meteen met een foutstatus en dezelfde e-mail — er wordt niet gewacht op vijf mislukkingen.

• Leveringen die alle 5 pogingen hebben verbruikt, verzamelen zich in een banner op de integratie. Alles opnieuw proberen zet ze opnieuw in de wachtrij en heractiveert een gepauzeerde integratie.

Testen

Stuur een test-event verschijnt bij de stap Afronden en opnieuw op de opgeslagen integratie. Het POST’t een gesynthetiseerde voorbeeldinzending — “John Doe” voor tekst, 42 voor getallen, john@example.com voor e-mail — ondertekend en met je aangepaste headers, precies zoals een echte levering. Vanuit de opgeslagen integratie wordt ook een verbindingstest-vermelding aan het gebeurtenislogboek toegevoegd.

Voor lokale ontwikkeling maak je je dev-server bereikbaar met een tunnel:

# ngrok
ngrok http 3000

# cloudflare tunnel

cloudflared tunnel --url http://localhost:3000

Veelgestelde vragen

Volgende stappen