Sign inGet Started

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.

BerichtGebruikte URL
Verzonden met options.callback_urlDie URL
Verzonden met options.callback_url ingesteld op nullGeen: events gaan naar je webhook-endpoints
Verzonden zonder deze URL, via een messagingprofielDe options.callback_url van het profiel
Ontvangen op een nummer van een messagingprofielDe inbound.callback_url van het profiel, daarna de options.callback_url
Geen URL uit een van de bovenstaandeGeen: 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

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.