Toggle sidebar

Payload-formaat

Wanneer een webhook afvuurt, stuurt Mach3Forms een HTTP POST naar jouw URL met een JSON-body. Dit artikel beschrijft de exacte structuur van die body, zodat je je receiver hierop kunt voorbereiden.

HTTP-request

POST <jouw webhook url>
Content-Type: application/json

{
  "type": "participant.responded",
  "survey": {
    "id": 123,
    "name": "Klanttevredenheid Q2 2026"
  },
  "data": {
    ...
  }
}

Top-level velden

Veld Beschrijving
type Het type event. Bij voltooide reacties altijd participant.responded
survey Object met basisinfo van de vragenlijst (id, name)
data De volledige deelnemer-resource met antwoorden

Het data-object

Het data-object volgt het formaat van de ParticipantResource uit de API. Voor een voltooide reactie krijg je deze velden:

  • id - uniek ID van de deelnemer
  • email - e-mailadres (alleen bij privé-vragenlijsten; null bij openbaar)
  • token - unieke deelnemer-token
  • invited_at - wanneer de uitnodiging is verstuurd (bij privé), bijvoorbeeld "15-04-2026 14:22"
  • responded_at - wanneer de reactie is binnengekomen
  • tags - array met tag-waarden van de deelnemer (eigenschappen zoals voornaam, afdeling, etc.)
  • answers - array met alle gegeven antwoorden, inclusief de bijbehorende vraag
  • reminder - informatie over verstuurde herinneringen
  • signature - handtekening-data, indien aanwezig

Voorbeeld-payload

{
  "type": "participant.responded",
  "survey": {
    "id": 123,
    "name": "Klanttevredenheid Q2 2026"
  },
  "data": {
    "id": 4567,
    "email": "deelnemer@voorbeeld.nl",
    "token": "abc123xyz",
    "invited_at": "10-04-2026 09:00",
    "responded_at": "12-04-2026 14:35",
    "tags": [
      { "key": "first_name", "value": "Jan" },
      { "key": "department", "value": "Marketing" }
    ],
    "answers": [
      {
        "id": 1,
        "value": "8",
        "score": null,
        "explanation": null,
        "question": {
          "id": 11,
          "name": "Welk cijfer geef je onze service?",
          "type": "score"
        }
      },
      {
        "id": 2,
        "value": "Snel en duidelijk geholpen, dank!",
        "score": null,
        "explanation": null,
        "question": {
          "id": 12,
          "name": "Kun je je antwoord toelichten?",
          "type": "text"
        }
      }
    ]
  }
}

Het answers-array

Per antwoord:

  • id - uniek ID van het antwoord
  • value - de gekozen of ingevulde waarde (string)
  • score - numerieke score bij vraagopties met scores (anders null)
  • explanation - eventuele toelichting bij het antwoord (anders null)
  • question - geneste vraag-resource met id, name, type

Voor meerkeuze-vragen (checkbox, images) bevat value de gekozen opties als puntkomma-gescheiden lijst (bijvoorbeeld "E-mail;Telefoon;Chat").

Het tags-array

Per tag:

  • key - interne naam van de tag (bijvoorbeeld first_name, department)
  • value - de waarde voor deze deelnemer (bijvoorbeeld Jan, Marketing)

Veelgestelde vragen

Nee. Een webhook met participant.responded vuurt alleen af bij een volledig voltooide vragenlijst.

Mach3Forms verstuurt de webhook één keer. Geeft je endpoint een fout of timeout? Dan is het bericht verloren. Bouw je receiver bij voorkeur als een lichte tussenlaag die de payload acceptert en intern op een queue zet.

Op dit moment is er geen handtekening (HMAC) op de payload. Beveilig je endpoint via een geheim in de URL (bijvoorbeeld /webhook?secret=xxx) of via IP-allowlisting van het Mach3Forms-uitgaande IP-adres.

Bij openbare vragenlijsten is email mogelijk null - gebruik dan id of token als unieke identifier in je systeem, of laat de deelnemer zelf zijn e-mailadres opgeven via een vraag in de vragenlijst.
Webhook testen