Wat doet de postback-service?
De Signhost postback-service levert realtime updates over transacties. Gebruik geen actieve polling (GET requests) om statusupdates te halen.
Postback URL registreren
Voor het registreren van de postback URL's kunnen twee manieren worden gebruikt:
Webportaal - statische URL
Registreer je postback URL’s via ons webportaal, zoals beschreven in deze handleiding. Bij het registreren van de postback URL in het portaal controleren we de beschikbaarheid en inrichting van de URL door een compleet lege postback te sturen. Deze postback moet ontvangen worden met een HTTP 2xx-response om de URL te kunnen registreren.
Door de URL in het webportaal te registreren kan je gebruik maken van extra security-opties zoals een authorization header en checksum-validatie.
POST-request - variabele URL's
Je kunt ook dynamisch een postback URL opgeven voor specifieke transacties door deze mee te geven in de POST-request.
Deze functionaliteit is bedoeld om postbacks te splitsen in verschillende ‘buckets’ die logisch zijn voor jouw implementatie, bijvoorbeeld om te differentiëren tussen verschillende omgevingen (staging, productie, etc.). Deze functionaliteit is niet bedoeld om postbacks per transactie te scheiden, omdat dit het postback-wachtrijsysteem omzeilt.
Dynamische postback-URL’s ondersteunen géén extra security-opties zoals een authorization header en checksum-validatie.
Hoe implementeer je onze postbacks op de juiste manier?
Om te voorkomen dat postbacks in een wachtrij komen te staan, raden wij het volgende aan zodra je een postback ontvangt:
Voer een security-validatie uit:
Controleer (indien van toepassing) de authorization header.
Body moet een geldige JSON zijn, anders naar stap 2.
Voer indien (indien van toepassing) een checksum-validatie uit:
JSON moet een
checksumveld bevatten, anders naar stap 2.Waarde van
checksummoet correct zijn, anders naar stap 2.
Geef altijd een HTTP 2xx status terug. Ook bij mislukte validatie, in dat geval de rest van de verwerking overslaan. Dit om postback-wachtrijen te voorkomen.
Verwerk en sla de geverifieerde postback op indien validatie geslaagd is.
Voer je verdere bedrijfslogica uit.
⚠️ Altijd een 2xx-response teruggeven
Je postback-endpoint moet altijd een HTTP-statuscode 2xx teruggeven, ook als de validatie faalt of er fouten optreden.
Doe je dit niet, dan zorgt Signhost ervoor dat alle volgende postbacks in een wachtrij worden geplaatst, wat kan leiden tot aanzienlijke vertragingen bij het ontvangen van transactie-updates.
Wat als de postback-URL niet bereikbaar is of geen verzoeken accepteert?
Als jouw postback-URL geen 2xx HTTP-response geeft, proberen we de postback opnieuw te versturen, met een oplopend tijdsinterval. Alle volgende postbacks komen dan in een wachtrij terecht en wachten tot de eerste postback succesvol is bevestigd met een 2xx status.
We blijven alleen nieuwe postbacks proberen zodra de eerste in de wachtrij is geslaagd. Na voltooiing van de eerste postback worden de achtergestelde verzoeken één voor één verwerkt. Als de eerste postback in de wachtrij binnen 48-72 uur niet afgeleverd kan worden, wordt de volledige wachtrij verwijderd.
Hoe voorkom je dat je data kwijtraakt?
Omdat postbacks kunnen mislukken, is het cruciaal om binnenkomende data altijd meteen te accepteren en op te slaan met een HTTP 2xx response. Zo voorkom je dat je data verliest en kun je later alsnog alles verwerken.
Verder lezen
Meer technische details over de postback-service vind je in onze complete API-documentatie.