Automate Your Workflows - EnageLab OTP Callback Settings Guide

Vue d'ensemble

Configurez des adresses de callback pour recevoir les callbacks de données du service OTP d'EngageLab concernant le « Statut des messages » et les « Messages de notification », et utilisez les données de callback pour l'analyse statistique, la relance stratégique ou le déclenchement d'alertes système.

• Statut des messages : Après l'envoi d'un message OTP par un utilisateur, ce statut inclut envoyé, délivré, lu, vérifié, etc.
• Messages de notification : Principalement des événements système, tels qu'un faible taux de vérification, un solde insuffisant, etc.

Configurer le callback

Dans la page « Gestion de la configuration » -> « Paramètres de callback », cliquez sur « Configurer le callback » pour mettre en place le callback pour le service OTP d'EngageLab.

Comme illustré ci-dessus, remplissez successivement « Description du callback », « Adresse de callback », « Nom d'utilisateur », « Autorisation », « Événements de callback », etc.

• Cochez les événements de callback pour pousser les informations vers votre adresse spécifiée lorsque les événements sélectionnés se produisent.
• Cliquez sur le côté droit du statut du message et de la réponse du message pour afficher les exemples correspondants.

Configurer l'adresse de callback

Lors de la configuration de l'adresse de callback, le système OTP d'EngageLab enverra une requête HTTP POST à l'adresse. Le service développeur correspondant doit répondre avec un code de statut HTTP 200 dans les 3 secondes, sinon le système considérera l'adresse comme invalide.

• Le service développeur doit uniquement répondre avec un code de statut HTTP 200, sans retourner de message de réponse.

Exemple de requête

Supposons que l'adresse de callback configurée soit https://example.engagelabotp.callback.com. Nous enverrons le message vide suivant à cette adresse, représenté par une commande curl :

              
              curl -X POST https://example.engagelabotp.callback.com -d ''

            

Exemple de réponse

Le service développeur à l'adresse de callback doit uniquement répondre avec un code de statut HTTP 200 après réception de la requête POST, comme ci-dessous :

              
              HTTP/1.1 200 OK
Content-Length: 0

            

Configuration du mécanisme de sécurité de l'adresse de callback

• Paramétrage du nom d'utilisateur

Cette opération est facultative. Si un nom d'utilisateur est défini, un secret doit également être renseigné.

Pour garantir que le message provient bien d'EngageLab, vous pouvez choisir d'authentifier la source des données POST.

Après configuration du nom d'utilisateur et du secret, les données envoyées par EngageLab incluront l'en-tête HTTP : X-CALLBACK-ID. La valeur de X-CALLBACK-ID sera timestamp={timestamp};nonce={nonce};username={username};signature={signature}

Par exemple :

              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

            

Le timestamp correspond à l'horodatage du message de callback (standard), nonce est un nombre aléatoire, et la signature est l'information de signature. La méthode de signature est : signature=HMAC-SHA256(secret, timestamp+nonce+username),

Voici un exemple de code Python pour calculer la signature :

              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret,
        msg='{}{}{}'.format(timestamp, nonce, username),
        digestmod=hashlib.sha256).hexdigest()

            

• Paramétrage de l'autorisation

Cette opération est facultative. Si votre adresse de callback nécessite une authentification pour les requêtes provenant d'EngageLab, veuillez fournir ici les informations d'authentification. EngageLab inclura cette Autorisation dans la requête.

Corps de la requête de callback

Lorsqu'un événement de callback est déclenché, le service OTP d'EngageLab enverra des données à l'adresse de callback.

Exemple de requête « Statut des messages »

Le statut des messages inclut :

• plan : Planifié pour l'envoi
• sent : Envoyé
• sent_failed : Échec de l'envoi
• delivered : Délivré
• delivered_failed : Échec de la livraison
• verified : Vérifié
• verified_failed : Échec de la vérification
• verified_timeout : Vérification expirée

              
              {
    "total": 2,
    "rows": [{
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "itime": 1704265712,
        "status": {
            "message_status": "plan",
            "status_data": {
                "msg_time": 170426571,
                "message_id": "1742442805608914944",
                "template_key": "auto_create_templateu25az170295320745",
                "business_id": "100917676394736"
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "itime": 1704265712,
        "status": {
            "message_status": "sent_failed",
            "status_data": {
                "msg_time": 1704265712,
                "message_id": "1742442805608914944",
                "template_key": "auto_create_templateu25az170295320745",
                "business_id": "100917676394736"
            },
            "error_code":5001,
            "error_detail":{
                "message":"sender config is invalid"
            }
        }
    }]
}

            

Exemple de requête « Messages de notification »

Événements :

• insufficient_balance : Solde en dessous du seuil d'alerte

              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,
                "balance_threshold": 2
            }
        }
    }]
}