Logo Site EngageLab Mark Colored TransparentDokumentation
OTP
Doku-Startseite
DokumentationAPI-Referenz
Suchen
Anmelden
API-Referenz/Callback-Konfiguration
API-ReferenzCallback-Konfiguration...

Hinweise zur Callback-Konfiguration

Zuletzt aktualisiert：7 days ago

Dieser Abschnitt erläutert, wie Sie die EngageLab OTP Callback-Adresse und zugehörige Sicherheitsprüfungsmechanismen konfigurieren, um die Zuverlässigkeit und Sicherheit der Callback-Daten zu gewährleisten.

Konfiguration und Überprüfung der Callback-Adresse

Nach der Konfiguration der Callback-Adresse sendet EngageLab OTP automatisch eine HTTP-POST-Anfrage an diese Adresse, um die Verfügbarkeit der Schnittstelle zu überprüfen. Ihr Dienst muss innerhalb von 3 Sekunden den HTTP-Statuscode 200 zurückgeben, andernfalls betrachtet das System die Adresse als nicht verfügbar.

Hinweis:
Um sicherzustellen, dass Callback-Daten ordnungsgemäß empfangen werden können, fügen Sie 119.8.170.74 und 114.119.180.30 zur Firewall-Whitelist Ihres Servers hinzu.

Anfragebeispiel

Angenommen, Ihre Callback-Adresse lautet https://example.engagelabotp.callback.com, sendet das System die folgende Anfrage:

curl -X POST https://example.engagelabotp.callback.com -d '{}'
              
              curl -X POST https://example.engagelabotp.callback.com -d '{}'
Diesen Codeblock im schwebenden Fenster anzeigen

Antwortanforderungen

Ihr Dienst muss lediglich den HTTP-Statuscode 200 zurückgeben und keinen Inhalt zurücksenden. Zum Beispiel:

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
Diesen Codeblock im schwebenden Fenster anzeigen

Hinweis:
Die Überprüfung der Callback-Adresse bewertet nur den HTTP-Statuscode und erfordert nicht die Rückgabe eines bestimmten Nachrichteninhalts. Stellen Sie sicher, dass Ihre Dienstschnittstelle innerhalb von 3 Sekunden korrekt mit 200 antworten kann.

Callback-Sicherheitsmechanismus

Um die Sicherheit und die vertrauenswürdige Herkunft der Callback-Daten zu gewährleisten, unterstützt EngageLab OTP mehrere Methoden zur Sicherheitsprüfung.

Überprüfung mit Benutzername und Secret (Optional)

  • Optionale Konfiguration. Wenn ein Benutzername festgelegt wird, muss auch ein Secret festgelegt werden.
  • Nach der Konfiguration fügt EngageLab jedem Callback-Request im HTTP-Header ein Feld X-CALLBACK-ID hinzu, im folgenden Format:
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
Diesen Codeblock im schwebenden Fenster anzeigen
  • Dabei gilt:
    • timestamp: Der Zeitstempel, zu dem der Callback gesendet wurde
    • nonce: Zufallszahl
    • username: Der von Ihnen konfigurierte Benutzername
    • signature: Signaturinformationen, die wie folgt berechnet werden

Methode zur Signaturberechnung (Python-Beispiel)

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{timestamp}{nonce}{username}'.encode(), digestmod=hashlib.sha256 ).hexdigest()
              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret.encode(),
        msg=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
Diesen Codeblock im schwebenden Fenster anzeigen
  • Der Server kann mit der oben genannten Methode die Gültigkeit des Callback-Requests überprüfen.

Authorization-Authentifizierung (Optional)

  • Wenn Ihre Callback-Schnittstelle eine Authentifizierung erfordert (z. B. Basic Auth, Bearer Token usw.), können Sie die Authorization-Informationen bei der Konfiguration angeben.
  • EngageLab übermittelt dieses Authorization-Feld automatisch bei der Anfrage, sodass Ihr Dienst die Identität der Anfrage bequem überprüfen kann.

Beschreibung der Callback-Ereignisse

Nachrichtenstatus

Der Nachrichtenstatus dient dazu, die Statusänderungen jeder Nachricht in ihrem Lebenszyklus zu verfolgen. Er wird verwendet, um den Fortschritt von Versand, Zustellung, Verifizierung und anderen Schritten der Nachricht in Echtzeit zu verstehen und erleichtert statistische Analysen, Ausnahmebehandlung und die Optimierung der Benutzererfahrung.

Ereigniskennung Beschreibung
plan Nachricht zum Versand geplant, gelangt in die Warteschlange
target_valid Zielnummer ist gültig
target_invalid Zielnummer ist ungültig
sent Nachricht erfolgreich gesendet
sent_failed Versand der Nachricht fehlgeschlagen
delivered Nachricht an das Gerät des Benutzers zugestellt
delivered_failed Nachricht gesendet, aber Zustellung an das Gerät des Benutzers fehlgeschlagen
verified Benutzer hat die OTP-Verifizierung erfolgreich abgeschlossen
verified_failed Verifizierung des Benutzers fehlgeschlagen
verified_timeout Benutzer hat die Verifizierung nicht innerhalb der vorgegebenen Zeit abgeschlossen, Zeitüberschreitung

Callback-Datenstruktur

Äußere Struktur

{ "total": 1, "rows": [ { // ReportLifecycle object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle object
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen
Feldname Typ Beschreibung
total int Anzahl der Datensätze in diesem Callback
rows array Array mit Lebenszyklus-Statusdaten

ReportLifecycle-Objekt

Feldname Typ Beschreibung
message_id string Eindeutige Nachrichten-ID
to string Empfängernummer
server string Diensttyp (z. B. otp)
channel string Kanaltyp
itime int64 Callback-Zeitstempel (Sekunden)
custom_args object Benutzerdefinierte Parameter (werden zurückgegeben, wenn übergeben)
status object Objekt mit Statusdetails

status-Objekt

Feldname Typ Beschreibung
message_status string Aktueller Nachrichtenstatus (siehe Tabelle unten)
status_data object Statusdatenobjekt
billing object Abrechnungsinformationsobjekt (wird bei Abrechnung zurückgegeben)
error_code int Fehlercode, 0 bedeutet kein Fehler
error_detail object Fehlerdetails (werden bei einem Fehler zurückgegeben)

status_data-Objekt

Feldname Typ Beschreibung
msg_time int64 Zeitstempel der Nachrichtenerstellung (Sek.)
message_id string Nachrichten-ID
current_send_channel string Name des aktuellen Sendekanals
template_key string Konfigurationsschlüssel der Vorlage
business_id string Business-ID

billing-Objekt (wird bei Abrechnung zurückgegeben)

Feldname Typ Beschreibung
cost float64 Kostenbetrag
currency string Währung, fest auf "USD"

In der Regel enthalten nur Nachrichten in der Phase „sent" Abrechnungsinformationen.

error_detail-Objekt (wird bei einem Fehler zurückgegeben)

Feldname Typ Beschreibung
message string Beschreibung der Fehlermeldung

Beispiel: Nachricht erfolgreich gesendet

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Beispiel: Versand der Nachricht fehlgeschlagen

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Nachrichtenbenachrichtigung

Nachrichtenbenachrichtigungen beziehen sich auf Geschäftsereignisse oder Warnungen auf Systemebene. Sie dienen dazu, die Geschäftsseite auf wichtige Informationen wie den Betriebsstatus des Dienstes, das Guthaben, die Vorlagenprüfung usw. aufmerksam zu machen und ermöglichen eine zeitnahe Bearbeitung sowie eine Risikowarnung.

Ereigniskennung Beschreibung
insufficient_verification_rate Verifizierungsrate unter dem festgelegten Schwellenwert
insufficient_balance Unzureichendes Kontoguthaben
template_audit_result Benachrichtigung über das Ergebnis der Vorlagenprüfung

Beispiel

{ "total": 1, "rows": [{ "server": "otp", "itime": 1712458844, "notification": { "event": "insufficient_balance", "notification_data": { "business_id": "1744569418236633088", "remain_balance": -0.005, // Current balance; "balance_threshold": 2 // Alert threshold; } } }] }
              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // Current balance;
                "balance_threshold": 2                       // Alert threshold;
            }
        }
    }]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Nachrichtenantwort

Die Nachrichtenantwort bezieht sich hauptsächlich auf Callback-Antwortereignisse bei der Interaktion mit Benutzern oder externen Systemen.

Ereigniskennung Beschreibung
uplink_message Upstream-Nachrichteninhalt, der vom Benutzer z. B. per SMS beantwortet wird

Beispiel

{ "total": 1, "rows": [ { "server": "otp", "itime": 1741083306, "message_id": "0", "business_id": "0", "response": { "event": "uplink_message", "response_data": { "message_sid": "SM1234567890", "account_sid": "AC1234567890", "from": "+1234567890", "to": "+0987654321", "body": "Hello, it's time to struggle!" } } } ] }
              
              {
    "total": 1,
    "rows": [
        {
            "server": "otp",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Systemereignisse

Systemereignisse umfassen betriebliche Vorgänge im Zusammenhang mit Konten, Vorlagen, API-Aufrufen usw. Sie erleichtern die Überwachung, Prüfung und automatisierte Verarbeitung wichtiger Vorgänge wie Kontoanmeldung, Schlüsseländerungen, API-Aufrufe usw.

Ereigniskennung Beschreibung
account_login Benachrichtigung über kontobezogene Anmeldevorgänge
key_manage Benachrichtigung über Vorgänge im Zusammenhang mit Schlüsseländerungen und -verwaltung
msg_history Benachrichtigung über Vorgänge im Zusammenhang mit Nachrichtenverlaufsabfragen
template_manage Benachrichtigung über Vorgänge zum Hinzufügen, Ändern und Löschen von Vorlagen
api_call Benachrichtigung über Vorgänge im Zusammenhang mit API-Schnittstellenaufrufen

Callback-Datenstruktur

Äußere Struktur

{ "total": 1, "rows": [ { // System event object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // System event object
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen
Feld Typ Beschreibung
total int64 Gesamtzahl der Ereignisse in diesem Callback
rows array Array mit Systemereignisobjekten

Systemereignisobjekt

Feld Typ Beschreibung
server string Fest auf "otp"
itime int64 Zeitstempel des Ereigniseintritts (Sek.)
system_event object Inhalt des Systemereignisses

system_event-Objekt

Feld Typ Beschreibung
event string Ereignistyp
data object Ereignisdaten

data-Objekt

Feld Typ Beschreibung
business_id string Business-ID
org_id string Organisations-ID
operator object Informationen zum Operator

operator-Objekt

Feld Typ Beschreibung
email string E-Mail des Operators (falls vorhanden)
api_key string API Key (falls vorhanden)
ip_address string IP des Vorgangs

Anfragestruktur

{ "total": 1, "rows": [ { "server": "otp", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "otp",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Kontoanmeldungsereignis

Feld Typ Beschreibung
action string login_success / login_failed / logout
fail_reason string Grund für das Fehlschlagen der Anmeldung, wird nur bei login_failed zurückgegeben

Beispiel

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen

Vorlagenverwaltungsereignis

Feld Typ Beschreibung
action string create template / update template / delete template
template_id string Vorlagen-ID
template_name string Vorlagenname

Beispiel

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen

Schlüsselverwaltungsereignis

Feld Typ Beschreibung
action string Enum-Werte:
create api_key: API Key erstellen
update api_key: API Key aktualisieren
delete api_key: API Key löschen
view api_secret: API Secret anzeigen
api_key string API Key
description string Beschreibung (optional)

Beispiel

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "New Key" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "New Key"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen

API-Aufrufereignis

Feld Typ Beschreibung
api_path string API-Pfad
method string HTTP-Methode

Beispiel

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen
Icon Solid Transparent White Qiyu
Vertrieb kontaktieren