Ga naar inhoud
Rayo SMSRayo SMS Documentatie

Aflever-callbacks (Webhooks) en handtekeningverificatie

De Rayo SMS Callback API (Webhooks) stuurt uw server vrijwel in realtime automatisch een melding zodra een uitgaand sms-bericht een definitieve afleverstatus bereikt (sent, delivered, not_delivered, unknown_delivery of failure) — waardoor u niet langer periodiek GET /v1/check_status hoeft aan te roepen.

Uw callback-endpoint configureren

Section titled “Uw callback-endpoint configureren”

U kunt uw webhook-listener configureren en testen in de Webapplicatie onder Geavanceerd -> Instellingen -> Callbacks (/settings/callbacks).

  1. Ga naar Geavanceerd (bovenste balk) -> Instellingen -> Callbacks (/settings/callbacks).
  2. Zet Ingeschakeld op Ja.
  3. Voer in het veld URL (Callback-URL) de volledige HTTPS-URL van uw webhook-endpoint in.
  4. Selecteer de gewenste HTTP-methode (HTTP Verb): get of post.
  5. Klik op Testen om een live test-webhookverzoek vanuit Rayo SMS naar uw server te sturen. Controleer of uw endpoint antwoordt met HTTP 200 OK en of de melding verschijnt:

    De Callback-API-eigenschappen lijken in orde te zijn

  6. Klik op Opslaan om uw configuratie op te slaan.

Webhook-handtekeningen verifiëren (Signing Secret)

Section titled “Webhook-handtekeningen verifiëren (Signing Secret)”

Omdat uw webhook-URL openbaar bereikbaar is via het internet, moet uw server controleren of elke binnenkomende callback daadwerkelijk afkomstig is van Rayo SMS en onderweg niet is gemanipuleerd of vervalst door een derde partij.

  • Handtekeningheader: Elk callback-HTTP-verzoek dat door Rayo SMS wordt verzonden, bevat een cryptografische handtekening in de HTTP-header X-sms-rayosms-nl-Signature.
  • Ondertekeningsgeheim van het account (Signing Secret): De handtekening wordt berekend met het unieke Signing Secret van uw account (weergegeven naast Signing Secret: op de pagina Geavanceerd -> Instellingen -> Callbacks).
  • Implementatiedetails: Raadpleeg de Callback-sectie in de API-referentie (https://api-docs.rayosms.nl) voor het exacte HMAC-verificatiealgoritme, de query-/body-parameters en het retry-gedrag.

Ondertekeningsgeheim roteren zonder downtime (Geheim laten verlopen)

Section titled “Ondertekeningsgeheim roteren zonder downtime (Geheim laten verlopen)”

Als uw beveiligingsbeleid periodieke sleutelrotatie vereist — of als u vermoedt dat uw huidige Signing Secret mogelijk is gelekt — kunt u een gecontroleerde vervaldatum instellen onder Geavanceerd -> Instellingen -> Callbacks:

  1. Open Geavanceerd -> Instellingen -> Callbacks (/settings/callbacks).
  2. Klik naast uw Signing Secret op Geheim laten verlopen….
  3. Selecteer wanneer het huidige geheim moet verlopen, zodat uw ontwikkelteam tijd heeft om de rotatie voor te bereiden.
  4. Als u een geplande rotatie wilt afbreken voordat de timer afloopt, klikt u op Geheim niet laten verlopen… om het geplande verlopen te annuleren.
  5. Zodra het ingestelde vervaltijdstip is bereikt, wordt het oude geheim automatisch buiten gebruik gesteld en wordt er onmiddellijk een nieuw Signing Secret gegenereerd.