FinBaze

FinBaze app-webhooks ontvangen

Registreer HTTPS-endpoints op je marketplace-app om ondertekende POSTs te krijgen wanneer domein-events plaatsvinden op geautoriseerde profielen.

Registreer HTTPS-endpoints op je marketplace-app om ondertekende POSTs te krijgen wanneer domein-events plaatsvinden op bedrijven die je app hebben geautoriseerd.

Stappen#

  1. Open je app in het developerportaal → Webhooks → Endpoint toevoegen.
  2. Vul een HTTPS-URL in (optioneel failover-URL) en selecteer de events die je nodig hebt (bijvoorbeeld sales_invoice.paid).
  3. Maak het endpoint aan en kopieer het signing-geheim één keer (fbwh_…). Bewaar het als een wachtwoord.
  4. Accepteer op je server POST JSON, verifieer X-FinBaze-Signature, en antwoord met 2xx binnen ongeveer 10 seconden.
  5. Installeer de app op een testprofiel, triggger een event (of gebruik Test-ping versturen), en controleer Recente deliveries.

Handtekening verifiëren#

FinBaze ondertekent de ruwe body met HMAC-SHA256:

  • Header: X-FinBaze-Signature: t=<unix>,v1=<hex>
  • Ondertekende string: <timestamp>.<rawBody>
  • Ook: X-FinBaze-Event, X-FinBaze-Delivery, X-FinBaze-Event-Id, X-FinBaze-Timestamp
  • Weiger requests waarbij |now - t| groter is dan 5 minuten (replay-bescherming)

Voorbeeld body:

{
  "id": "delivery-uuid",
  "event": "sales_invoice.paid",
  "eventId": "sales_invoice.paid:…",
  "created": "2026-01-15T12:00:00.000Z",
  "appId": "your-client-id",
  "profileId": "…",
  "entityId": "…",
  "data": { }
}

Retries en failover#

  • Mislukte deliveries worden opnieuw geprobeerd met backoff (30s → 2m → 10m → 1u → 6u → 24u), tot 8 pogingen.
  • Als er een failover-URL is ingesteld, probeert FinBaze die in dezelfde poging na een mislukte primary.
  • Antwoord met 410 Gone om het endpoint permanent uit te schakelen.
  • Na te veel opeenvolgende mislukkingen wordt het endpoint automatisch uitgeschakeld; schakel het opnieuw in via het portaal.

Wat gebeurt er daarna?#

Je integratie kan vrijwel real-time reageren in plaats van te pollen. Roteer het signing-geheim bij een lek; gebruik Opnieuw op een mislukte delivery nadat je je receiver hebt hersteld.

Veelgestelde vragen#

Welke profielen sturen events naar mijn endpoint?

Alleen profielen die je app hebben geautoriseerd (geïnstalleerd). Eén endpoint ontvangt events van alle geautoriseerde profielen.

Is dit hetzelfde als de automation-actie send_webhook?

Nee. Automations gebruiken een apart optioneel signature-schema. App-webhooks gebruiken het t=,v1=-schema hierboven.

Gerelateerde artikelen#