Webhooks

Met webhooks reageren integraties op wijzigingen in Resolved zonder de API te pollen. Resolved levert events met een HTTP-POST naar URL's die jij configureert.

Er zijn twee outbound-webhooksystemen. Het zijn aparte resources met verschillende eigenaarschap- en leveringsregels.

Client-webhooks#

Gebruik client-webhooks wanneer een klant betalings-events voor het eigen clientprofiel wil. Je kunt per client meerdere webhooks aanmaken; elk heeft een eigen URL, eventlijst en secret.

Registratie#

Maak een webhook aan met de client-IRI, een naam, een of meer eventnamen en een publiek bereikbare URL (http of https, met een echte TLD — private / loopback-hosts worden geweigerd).

Bij aanmaken genereert Resolved een secret en geeft die terug op de webhook-resource. Bewaar die veilig; je hebt die nodig om leveringen te verifiëren.

Events (momenteel geleverd)#

Alleen actieve webhooks die het event in hun lijst hebben, ontvangen een levering.

Levering#

• Methode: POST
• Headers: Content-Type: application/json, X-Resolved-Signature: sha256=<hex>
• Body: JSON-betalingssnapshot plus caseFile en @event

Voorbeeldvorm:

{
  "@event": "case_file.payment.confirmed",
  "id": 123,
  "amount": 15000,
  "paidTo": "client",
  "confirmedAt": "2026-07-09T08:30:00+00:00",
  "createdAt": "2026-07-09T08:29:00+00:00",
  "updatedAt": "2026-07-09T08:30:00+00:00",
  "caseFile": {
    "id": 456
  }
}

Handtekeningen verifiëren#

Herbereken HMAC-SHA256 over de ruwe request-body met het webhook-secret en vergelijk die met de hex-digest in X-Resolved-Signature (strip de prefix sha256=) in constante tijd voordat je de payload vertrouwt.

Reageren en herhaalpogingen#

Geef snel een 2xx-status terug om ontvangst te bevestigen. Doe het echte werk asynchroon. Non-2xx-antwoorden en transportfouten worden opnieuw geprobeerd. Inactieve webhooks of niet-geabonneerde events niet.

Leveringen kunnen meer dan eens binnenkomen — maak handlers idempotent (bijvoorbeeld op payment-id + @event).

App Store-app-webhooks#

App Store-ontwikkelaars registreren webhooks op de App-resource zelf (AppWebhook), niet op elke klantinstallatie.

Registratie#

Gebruik de API:

• Collectie: GET /api/apps/{id}/app_webhooks
• Create / update / delete: /api/app_webhooks

Schrijfbare velden:

• app — de App-IRI
• webhookUrl — publiek bereikbare URL (zelfde URL-regels als client-webhooks)
• events — lijst eventnamen waarop je abonneert (1–100)
• responseHandlingType — 1 (FIRE_AND_FORGET) of 2 (WAIT_FOR_SUCCESSFUL_RESPONSE)
• active — of het endpoint leveringen mag ontvangen

Je kunt meerdere webhooks aan één App hangen (andere URL's of eventfilters). Een installatie wijzigen maakt deze rijen niet aan of weg.

Leveringsgedrag#

De App Store-webhook-API laat je endpoints, eventfilters en response handling op je App registreren. Wanneer een matching event naar een actieve app-webhook wordt gestuurd, doet Resolved een POST met JSON naar webhookUrl en zet @event in de payload.

• FIRE_AND_FORGET — HTTP-status wordt genegeerd
• WAIT_FOR_SUCCESSFUL_RESPONSE — non-2xx wordt opnieuw geprobeerd

App-webhooks sturen geen X-Resolved-Signature. Gebruik client-webhooks als je HMAC nodig hebt, of beveilig je endpoint op een andere manier (private URL, netwerkrestricties, enz.).