Webhooks

Onder Beheer, Koppelingen, tabblad API staat Webhooks. Klik op Endpoint toevoegen, plak de URL van je ontvanger, geef er eventueel een omschrijving bij en vink aan welke gebeurtenissen je wilt. Nu is dat er één: proposal.signed, de klant heeft een offerte getekend. De inhoud is dezelfde vorm die de API teruggeeft, dus je hergebruikt de code die je al hebt.

De URL moet https zijn en naar het open internet wijzen. Na het opslaan zie je het signing secret één keer: kopieer het meteen naar je secret manager, want daarna tonen we het niet opnieuw.

Elke levering draagt drie headers: webhook-id (het id van de gebeurtenis), webhook-timestamp (het moment van deze poging) en webhook-signature. Bereken de handtekening zelf uit het secret, het id, de timestamp en de ruwe body, en vergelijk. Wijk je af, dan is het bericht niet van ons.

Het veld id in de body is waar je op ontdubbelt: een nieuwe poging van dezelfde gebeurtenis draagt hetzelfde id, en dat geldt ook als dezelfde gebeurtenis naar twee endpoints gaat. De timestamp is per poging, dus daarmee weiger je een herhaald oud verzoek.

Antwoordt je ontvanger niet met een 2xx, dan proberen we het opnieuw: eerst na vijf seconden, dan na vijf minuten, en zo oplopend tot ongeveer 28 uur na de eerste poging. Daarna geven we die levering op. In de lijst zie je per levering de status: In wachtrij, Wordt herhaald, Geleverd of Opgegeven, met het aantal pogingen erbij. Met Opnieuw sturen stuur je er zelf eentje nog eens heen.

Blijft een endpoint drie dagen lang niets accepteren, dan zetten we hem uit. Dat voorkomt een wachtrij die eindeloos doorgroeit naar een adres dat niet meer bestaat. Je repareert je ontvanger en zet het endpoint zelf weer aan. Je kunt een endpoint ook tijdelijk uitzetten tijdens onderhoud.