Callback-URL's voor SMS
Een callback-URL ontvangt de events van één SMS-bericht, of van elk bericht op een messagingprofiel, in plaats van je webhook-endpoints. Gebruik een callback-URL als een bericht of een programma een eigen ontvanger nodig heeft.
Beheer het ondertekeningsgeheim, de geschiedenis van pogingen en het opnieuw afspelen in het dashboard, of via de API en de bird webhooks callbacks-opdrachten. Stel de URL van een profiel in wanneer je een messagingprofiel aanmaakt of er een bijwerkt.
Kies waar events naartoe gaan
De URL wordt één keer bepaald, op het moment dat het bericht wordt geaccepteerd, en blijft gelden zolang het bericht bestaat. Als je het profiel later wijzigt, wordt een bericht dat al onderweg is niet omgeleid.
| Bericht | Gebruikte URL |
|---|---|
Verzonden met options.callback_url | Die URL |
Verzonden met options.callback_url ingesteld op null | Geen: events gaan naar je webhook-endpoints |
| Verzonden zonder deze URL, via een messagingprofiel | De options.callback_url van het profiel |
| Ontvangen op een nummer van een messagingprofiel | De inbound.callback_url van het profiel, daarna de options.callback_url |
| Geen URL uit een van de bovenstaande | Geen: events gaan naar je webhook-endpoints |
De URL moet HTTPS zijn, mag maximaal 2.048 tekens lang zijn en moet een openbaar adres hebben. Een privé-, loopback- of link-local host geeft 422 terug.
In de lijst met callback-pogingen zie je waar het event van een ontvangen bericht is afgeleverd.
Wat de URL vervangt
Zolang er een URL geldt, slaan de events van dat bericht je webhook-endpoints over. Andere berichten in de werkruimte bereiken ze nog wel. Een mislukte callback valt niet terug op je endpoints: gebruik opnieuw afspelen om de callback te herstellen.
MCP Events-abonnementen en connector-endpoints ontvangen de events van het bericht nog steeds.
Met de callback_events van een messagingprofiel kies je welke uitgaande events naar de URL gaan, uit sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected en sms.expired. Een event dat niet in de lijst staat, bereikt voor dat bericht ook geen enkel webhook-endpoint. Een profiel zonder lijst en een verzending zonder profiel leveren elk uitgaand event af. sms.received wordt nooit gefilterd. De payloads zijn de SMS-events.
Handtekeningen verifiëren
Callbacks gebruiken dezelfde Standard Webhooks-headers en HMAC-SHA256-handtekening als webhook-endpoints, dus je bestaande verificatiecode werkt ongewijzigd. De sleutel is het callback-ondertekeningsgeheim van je werkruimte: één geheim dat alle callback-URL's en alle webhookverzoeken van spraaksequenties delen, dus een rotatie geldt voor beide.
Het eerste geheim wordt nooit getoond. Roteer het om er een te krijgen dat je kunt gebruiken, onder Webhooks → Direct callbacks in het dashboard of met Rotate callback signing secret. Het nieuwe geheim wordt maar één keer getoond, dus sla het op voordat je de pagina verlaat. De eerste 24 uur wordt elke callback ondertekend met zowel het oude als het nieuwe geheim, zodat je het nieuwe geheim kunt uitrollen zonder afleveringen te missen. Een werkruimte heeft maximaal 5 geheimen die tegelijk geldig zijn, dus een nieuwe rotatie binnen die overlap kan worden geweigerd. Een rotatie wordt binnen ongeveer een minuut van kracht.
Roteer het geheim voordat je op verificatie vertrouwt: tot die tijd dragen callbacks een handtekening die is gemaakt met een geheim dat je niet kunt lezen.
Nieuwe pogingen en duplicaten
Callbacks volgen het schema voor nieuwe pogingen van webhook-endpoints: acht pogingen verspreid over ongeveer 27,5 uur, en een 2xx binnen 15 seconden telt als geslaagd. Anders dan een endpoint wordt een callback-URL nooit gepauzeerd.
Elke gebeurtenis wordt minstens één keer afgeleverd, zonder vaste volgorde. Verwijder duplicaten op basis van de header webhook-id en sorteer op de timestamp in de payload.
Mislukte callbacks vinden en opnieuw afspelen
Het tabblad Direct callbacks onder Webhooks in het dashboard en List callback delivery attempts tonen de callback-pogingen van de werkruimte, de nieuwste eerst, met de URL, de status die je ontvanger teruggaf en de latentie. Pogingen worden drie dagen bewaard.
Replay failed callback deliveries zet één extra poging in de wachtrij voor elk event waarvan de callbacks mislukten binnen een tijdvenster dat je kiest, net zoals endpoint-afleveringen opnieuw afspelen dat voor endpoints doet. Een event dat binnen dat venster ook succesvol is afgeleverd, wordt overgeslagen. Een geslaagde aflevering buiten het venster telt niet mee, dus dat event wordt opnieuw verzonden. Eén keer opnieuw afspelen verzendt maximaal de oudste 10.000 mislukte events in het venster; speel na een langere storing opnieuw af met een latere starttijd voor de rest.
Opnieuw afspelen verzendt naar de URL die bij de mislukte pogingen is vastgelegd, niet naar je webhook-endpoints en niet naar de huidige URL van het profiel. Zo herstel je een storing bij je ontvanger. Een bericht dat naar een verkeerde URL is verzonden, kun je zo niet herstellen; verzend dat bericht opnieuw. Opnieuw afspelen telt mee voor dezelfde daglimiet als het opnieuw afspelen van endpoint-afleveringen.
Volgende stappen
- SMS-gebeurtenissen: de payload van elke gebeurtenis
- Webhooks en gebeurtenissen: handtekeningen, nieuwe pogingen en opnieuw afspelen uitgebreid beschreven
- SMS verzenden: het verzendverzoek
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.