SMS-Callback-URLs

Eine Callback-URL empfängt anstelle Ihrer Webhook-Endpunkte die Ereignisse einer einzelnen SMS-Nachricht oder aller Nachrichten eines Messaging-Profils. Verwenden Sie sie, wenn eine Nachricht oder ein Programm einen eigenen Empfänger braucht.

Das Signaturgeheimnis, den Verlauf der Zustellversuche und die erneute Zustellung verwalten Sie im Dashboard oder über die API und die Befehle von bird webhooks callbacks. Die URL eines Profils legen Sie fest, wenn Sie ein Messaging-Profil erstellen oder es aktualisieren.

Festlegen, wohin Ereignisse gehen

Die URL wird einmalig ermittelt, wenn die Nachricht angenommen wird, und bleibt für die gesamte Lebensdauer der Nachricht erhalten. Eine spätere Änderung am Profil leitet eine bereits laufende Nachricht nicht um.

Die URL muss HTTPS sein, darf höchstens 2.048 Zeichen lang sein und muss eine öffentliche Adresse haben. Ein privater, Loopback- oder Link-Local-Host gibt 422 zurück.

Wohin das Ereignis einer empfangenen Nachricht zugestellt wurde, zeigt die Liste der Callback-Zustellversuche.

Was die URL ersetzt

Solange eine URL gilt, gehen die Ereignisse dieser Nachricht nicht an Ihre Webhook-Endpunkte. Andere Nachrichten im Workspace erreichen sie weiterhin. Ein fehlgeschlagener Callback wird nicht ersatzweise an Ihre Endpunkte zugestellt. Stellen Sie ihn stattdessen erneut zu.

MCP Events-Abonnements und Connector-Endpunkte erhalten die Ereignisse der Nachricht weiterhin.

Die callback_events eines Messaging-Profils legen fest, welche ausgehenden Ereignisse an die URL gehen. Zur Auswahl stehen sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected und sms.expired. Ein Ereignis, das nicht in der Liste steht, erreicht für diese Nachricht auch keinen Webhook-Endpunkt. Ein Profil ohne Liste und ein Versand ohne Profil liefern alle ausgehenden Ereignisse. sms.received wird nie gefiltert. Die Nutzlasten sind die SMS-Ereignisse.

Signaturen prüfen

Callbacks verwenden dieselben Standard Webhooks-Header und dieselbe HMAC-SHA256-Signatur wie Webhook-Endpunkte, sodass Ihr vorhandener Prüfcode unverändert funktioniert. Der Schlüssel ist das Callback-Signaturgeheimnis Ihres Workspace. Dieses eine Geheimnis gilt für alle Callback-URLs und alle Webhook-Anfragen von Sprachsequenzen, daher wirkt sich eine Rotation auf beide aus.

Das erste Geheimnis wird nie angezeigt. Rotieren Sie es im Dashboard unter Webhooks → Direct callbacks oder mit Rotate callback signing secret, um ein verwendbares Geheimnis zu erhalten. Das neue Geheimnis wird nur einmal angezeigt, speichern Sie es also, bevor Sie die Seite verlassen. In den folgenden 24 Stunden wird jeder Callback sowohl mit dem alten als auch mit dem neuen Geheimnis signiert. So können Sie das neue Geheimnis bereitstellen, ohne Zustellungen zu verlieren. Ein Workspace kann höchstens 5 gleichzeitig gültige Geheimnisse haben, daher kann eine weitere Rotation innerhalb der Überlappung abgelehnt werden. Eine Rotation wird innerhalb von etwa einer Minute wirksam.

Rotieren Sie das Geheimnis, bevor Sie sich auf die Prüfung verlassen. Bis dahin tragen Callbacks eine Signatur, die mit einem Geheimnis erstellt wurde, das Sie nicht lesen können.

Erneute Versuche und Duplikate

Callbacks folgen dem Zeitplan für erneute Versuche bei Webhook-Endpunkten: acht Zustellversuche über etwa 27,5 Stunden, und ein 2xx innerhalb von 15 Sekunden gilt als Erfolg. Anders als ein Endpunkt wird eine Callback-URL nie pausiert.

Die Zustellung erfolgt mindestens einmal und ohne feste Reihenfolge. Entfernen Sie Duplikate anhand des Headers webhook-id, und sortieren Sie nach timestamp in der Nutzlast.

Fehlgeschlagene Callbacks finden und erneut zustellen

Der Tab Direct callbacks unter Webhooks im Dashboard und List callback delivery attempts zeigen die Callback-Zustellversuche des Workspace, die neuesten zuerst, mit URL, dem von Ihrem Empfänger zurückgegebenen Status und der Latenz. Zustellversuche werden drei Tage lang aufbewahrt.

Replay failed callback deliveries reiht für jedes Ereignis, dessen Callbacks in einem von Ihnen gewählten Zeitfenster fehlgeschlagen sind, einen weiteren Zustellversuch ein, so wie die erneute Zustellung an Endpunkte es für Endpunkte tut. Ein Ereignis, das innerhalb dieses Zeitfensters auch erfolgreich zugestellt wurde, wird übersprungen. Ein Erfolg außerhalb des Zeitfensters zählt nicht, daher wird dieses Ereignis erneut gesendet. Eine erneute Zustellung sendet höchstens die ältesten 10.000 fehlgeschlagenen Ereignisse im Zeitfenster. Nach einem längeren Ausfall starten Sie für den Rest eine weitere erneute Zustellung mit einer späteren Startzeit.

Eine erneute Zustellung sendet an die URL, die bei den fehlgeschlagenen Zustellversuchen gespeichert ist, weder an Ihre Webhook-Endpunkte noch an die aktuelle URL des Profils. Sie behebt einen Ausfall bei Ihrem Empfänger. Eine an eine falsche URL gesendete Nachricht kann sie nicht retten, senden Sie diese Nachricht daher erneut. Erneute Zustellungen zählen zum selben Tageslimit wie erneute Zustellungen an Endpunkte.

Nächste Schritte

• SMS-Ereignisse: die Nutzlast jedes Ereignisses
• Webhooks & Ereignisse: Signaturen, erneute Versuche und erneute Zustellung im Detail
• SMS senden: die Sendeanfrage