> Denne siden dokumenterer nyttelastkontrakten og REST-abonnements-API-et. For å sette opp en egendefinert webhook for skjemaet ditt i > grensesnittet, se Webhooks. >
POST <your-url> med Content-Type: application/json.
Content-Type: application/json
X-Formstep-Signature: t={timestamp},sha256={hex} — vises når en signeringsnøkkel er satt opp (se
nedenfor)
X-Formstep-Event-Id og X-Formstep-Event-Type — samme verdier som id og type i
kroppen, slik at du kan deduplisere og rute før parsing. En forespørsel-callback sender de samme
to.
Content-Type, som ikke kan
overstyres. Native abonnementer opprettet via webhooks.create har ingen egendefinerte hoder.
Når du setter opp en webhook-integrasjon, velger du hvilken hendelse som utløser leveranser:
De tre request_*-hendelsene abonneres gjennom webhooks.create og er det Formstep-appene for Zapier, Make og n8n
lytter på. Hver leverer samme konvolutt som en forespørsel-callback sender, signert med abonnementets
egen hemmelighet. Testforespørsler når aldri et abonnement, og requests.replayCallback sender bare callbacken på nytt. Ett
abonnement, én hendelse: submission_created er trafikk fra delelenker og request_completed er trafikk fra
forespørsler, så en fullført forespørsel utløser aldri submission_created, og et skjema med begge abonnementene mottar én
leveranse per fullføring. En redigering når bare et submission_updated-abonnement, aldri et submission_created
-abonnement. Webhooken du setter opp i Skjemainnstillinger har ikke noe valg av hendelse: den mottar første innsendinger og redigeringer
likt, skilt fra hverandre med type.
Feltet type i JSON-kroppen forteller deg hva som skjedde:
submission.completed — en ny fullført innsending
submission.updated — en eksisterende innsending ble redigert
submission.abandoned — et innsendingutkast ble forlatt etter det konfigurerte inaktivitetsvinduet
En forespørsel-callback og et request_*-abonnement bruker samme konvolutt med{' '}
request.completed, request.expired og request.canceled, så én parser leser alle seks.
answers er det flate {'{ field key: value }'}-objektet, med nøkler satt til feltnøklene som ble frosset ved
publisering. Les den når en arbeidsflyt forgrener seg eller lagrer en verdi: answers.email, ingen array å gå gjennom. Et
valgsvar er det valgte alternativets nøkkel — key-en som fields.list lister for det
alternativet — så den er den samme uansett hvilket språk respondenten svarte på. En dato er en ISO-streng, et tall et tall, et flervalg en
array av alternativnøkler. Ubesvarte felt utelates, sendes aldri som null.
display bærer de samme nøklene med menneskelig lesbar tekst: alternativets etikett i stedet for nøkkelen, en formatert dato,
en sammenslått liste. Les den når en person skal se verdien — en Slack-melding, en regnearkcelle, en e-post.
En gjentakende gruppe vises i answers én gang, under gruppens egen feltnøkkel, som en array av radobjekter nøklet med hvert
medlems feltnøkkel — answers.attendees[0].attendee_name ovenfor — og i display som én linje med radene slått
sammen. Et medlem løftes aldri opp til toppnivået. Beregnede felt vises i begge listene
under det beregnede feltets navn som nøkkel (answers.total).
Et Planlegg avtale-spørsmål og et Betalingsfelt har hver et objekt i answers, under spørsmålets feltnøkkel, og én tekstlinje
i display. Tidene er ISO-tidspunkter, så et regneark eller en arbeidsflyt kan tolke dem uansett hvilket språk respondenten
svarte på:
En bestillings status er confirmed, rescheduled, cancelled, rejected{' '}
eller no_show. En betalings er paid, partially_refunded, refunded eller{' '}
disputed, og amount er i valutaens hovedenhet: 40 er $40.00. Når Cal.com flytter en bestilling
eller Stripe refunderer en betaling etter innsendingen, oppdaterer Formstep objektet, slik at submissions.list og senere
hendelser viser gjeldende tilstand; ingen ny hendelse sendes for endringen.
Før apiVersion 2026-09-24 ble en bestilling sendt som én setning i answers, og en betaling ble ikke
sendt i det hele tatt.
Webhookens felttilordning gjelder for begge listene samtidig: velg «valgte» felt og resten utelates; gi et felts kolonne nytt navn, og det
nye navnet er nøkkelen dets i answers og display likt. Et felt skjemaet publiserte før feltnøkler fantes, sendes
ut under element-IDen sin; publiser skjemaet på nytt for å gi det en lesbar nøkkel.
Hendelsen gjentar ikke hvert felts tittel og type. Les dem fra fields.list, som er stabil per{' '}
data.form.snapshotId, slik at du kan mellomlagre feltlisten og bare hente på nytt når øyeblikksbilde-IDen endres. En mottaker
som ikke kan gjøre et andre kall, kan slå på Send feltlisten med hver hendelse i webhookens innstillinger; hendelsen
bærer da data.schema, ett element per felt. Et valgspørsmål lister options sine og en matrise rows{' '}
og columns sine, hver som {'{ key, label }'}, slik at nøklene i answers løses til etiketter uten et
andre kall:
På den egendefinerte webhooken som er konfigurert i skjemainnstillingene, bærer en innsending som
besvarte en forespørsel ett ekstra objekt inne i data, request. Det er
fraværende på hver offentlig-lenke-innsending, så tilstedeværelsen er hvordan den mottakeren skiller de to kanalene fra hverandre. Et
Zapier-, Make- eller n8n-abonnement ser det aldri: forespørseltrafikk når et abonnement som request.completed, som bærer hele
request-blokken.
id — forespørselen denne innsendingen besvarte. Send den til requests.get for hele bildet.
externalId og metadata — din egen bokføring, nøyaktig slik du oppga den i requests.create. Hver
er kun til stede når den ble satt.
> En innsendings-webhook utløses ved en innsending; request-blokken navngir bare forespørselen den besvarte. En{' '}
> callback utløses når en forespørsel avsluttes — fullført, utløpt eller kansellert — og bærer{' '}
> context og outcome. Utløp og kansellering har ingen innsending, så ingen innsendings-webhook utløses noensinne
> for dem. For å høre at en forespørsel avsluttes uten en callback-URL, abonner på request_completed,{' '}
> request_expired eller request_canceled gjennom webhooks.create.
>
data.submission.pdfUrl er en lenke til innsendings-PDF-en. Et skjema med en egendefinert webhook eller et Zapier-, Make-
eller n8n-abonnement beholder en PDF av hver innsending, så hendelsene til skjemaet har med lenken. Den er null bare når
innsendingen ikke har noen PDF.
data.submission.language er BCP-47-koden for språket respondenten sendte inn skjemaet på (for oversatte skjemaer). Den er{' '}
null for skjemaer med ett enkelt språk. Bruk den til å rute eller forgrene basert på respondentens språk uten et eget
oppslag.
Når du abonnerer på submission_abandoned, sjekker Formstep for inaktive utkast hver time. Hvis et utkast har vært inaktivt
forbi det konfigurerte inaktivitetsvinduet, sender Formstep en leveranse.
Native API-integrasjoner må sende idleWindow til webhooks.create. Godtatte verdier er 12h,{' '}
1d, 3d, og 1w. Det finnes ingen implisitt standard; et forlatt-abonnement uten en verdi avvises.
Nyttelastens form er identisk med en fullført innsending. To forskjeller:
answers og display.
submittedAt
{' '}
— faller tilbake til avsendingstidspunktet siden respondenten aldri formelt sendte inn.
Hver integrasjon sender ut maks én gang per forlatt utkast. Etter leveranse utelukkes utkastet fra fremtidige søk.
Hver webhook har sin egen signeringsnøkkel — satt opp i grensesnittet når du konfigurerer en egendefinert webhook, eller med den valgfrie
parameteren signingSecret (32–255 tegn) på webhooks.create. Det er ikke arbeidsområdens signeringshemmelighet
for forespørsler, som brukes for forespørsel-callbacks, men hodet og algoritmen er identiske, så én
verifiserer håndterer begge.
Hver signert leveranse bærer X-Formstep-Signature: t={seconds},sha256={hex}. Sammendraget er en
HMAC-SHA256 av {t}.{raw body}, nøklet med hemmeligheten din. To regler: hash den rå{' '}
kroppen før noen parsing eller re-serialisering, og sammenlign i konstant tid.
Formstep håndhever ikke et repriseringsvindu, så toleransen ovenfor er din å velge. Å endre hemmeligheten trer i kraft ved neste forsøk, inkludert nye forsøk som allerede er underveis — oppdater mottakeren din først.
> ⚠️ **Verifiser alltid i produksjon** >Uten verifisering kan hvem som helst som oppdager URL-en din poste falske innsendinger.
Formstep gjør opptil 5 forsøk per leveranse — 1 første forsøk og 4 nye forsøk — med minst 1, 2, 4 og 8 minutter mellom hvert. Formstep ser
etter forfalte nye forsøk hvert 30. minutt, så et nytt forsøk kan komme opptil en halvtime etter at tilbakegangen er over, og det siste
forsøket om lag to timer etter det første. En Retry-After-header på svaret ditt respekteres når den ber om lenger tid enn
neste tilbakegangssteg. En leveranse regnes som mislykket hvis endepunktet ditt:
Ett tilfelle prøves aldri på nytt: et mål som er blokkert, ikke kan slås opp, eller peker til en privat adresse. URL-en revalideres — inkludert DNS — umiddelbart før hvert forsøk, så en vert som slutter å være tillatt feiler leveransen med én gang i stedet for å bruke opp budsjettet.
Etter 5 påfølgende mislykkede leveranser pauses integrasjonen. Løs endepunktet og aktiver den på nytt fra Skjemainnstillinger → Integrasjoner; en vellykket leveranse nullstiller telleren.
Leveranser som prøves på nytt for samme hendelse gjenbruker samme id, så du kan deduplisere ved å lagre behandlede id-er. En
genuint ny hendelse — for eksempel at en respondent redigerer innsendingen sin — kommer med en ny id og{' '}
type: "submission.updated": på Skjemainnstillinger-webhooken, eller på et submission_updated-abonnement.{' '}
createdAt er tidspunktet hendelsen ble satt i kø, ikke tidspunktet forsøket ble gjort, så den forblir den samme på tvers av
nye forsøk også. For å skille redigeringer fra hverandre, les data.submission.editCount: den teller oppover for hver
redigering, og data.submission.updatedAt forteller når den siste skjedde.
Både integrasjonsoppsettet og detaljpanelet har en Send test-knapp. Den sender et eksempel på den abonnerte hendelsen til
URL-en din slik at du kan verifisere tilkoblingen uten å vente på en ekte innsending eller forespørsel. De samme eksemplene er
tilgjengelige over API-et som submissions.sample og requests.sample.
For lokal utvikling, eksponer dev-serveren din med en tunnel:
``` # ngrok ngrok http 3000 # cloudflare tunnel cloudflared tunnel --url http://localhost:3000 ``` > 💡 **Lokal utvikling** >Bruk tunnel-URL-en som webhook-endepunkt, og trykk deretter Send test for å verifisere ende-til-ende.