Webhooks
Recevez en temps réel les événements d'activation sur votre serveur, vérifiez l'en-tête SmsGrab-Signature et comprenez les nouvelles tentatives, les envois de test et la désactivation automatique.
Sur cette page
Les webhooks envoient les événements à votre serveur au moment où ils se produisent, pour vous éviter d'interroger l'API. Un webhook appartient à une clé API. Il reçoit les événements des numéros achetés avec cette clé, ainsi que les alertes de solde bas de votre compte.
Événements
| Événement | Quand |
|---|---|
activation.created |
Un numéro a été acheté |
activation.code_received |
À chaque nouveau SMS, avec tous les messages reçus |
activation.completed |
Terminé par vous, ou temps écoulé après un code |
activation.cancelled |
Annulé avant un code, remboursé |
activation.expired |
Aucun code à temps, remboursé |
activation.refunded |
Tout remboursement du débit |
balance.low |
Votre solde est passé sous le seuil que vous avez défini |
webhook.test |
Un envoi de test que vous avez lancé |
Créer un webhook
Dans Compte > Développeurs, ouvrez une clé et ajoutez un webhook avec son URL, les événements voulus et une description facultative. Chaque clé peut avoir jusqu'à 3 webhooks.
L'URL doit :
- commencer par
https://; - utiliser un nom d'hôte, pas une adresse IP ;
- mener à une adresse publique. Les réseaux privés, localhost et les plages similaires sont refusés.
Vous recevez un secret de signature qui commence par whsec_. Comme une clé API, il ne s'affiche qu'une fois. Vous pourrez le renouveler plus tard, ce qui demande aussi votre mot de passe.
À quoi ressemble un envoi
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: SmsGrab-Webhooks/1.0
SmsGrab-Event: activation.code_received
SmsGrab-Delivery: 9f7d6c1e-2b44-4c1a-8f0e-6a3d2c1b0e9f
SmsGrab-Signature: t=1790503200,v1=3b9a0c…
{ "id": "evt_4e1f…", "type": "activation.code_received", "created_at": "2026-09-27T10:06:12.004Z",
"api_version": "2026-09-27", "data": { "activation": { "id": "5c1d0c2e-…", "status": "CODE_RECEIVED" } } }
Vérifier la signature
SmsGrab-Signature contient un horodatage t et v1, le HMAC-SHA256 de t, d'un point et du corps brut de la requête, calculé avec votre secret. Rejetez les envois dont l'horodatage s'écarte de plus de 300 secondes de votre horloge, et comparez les signatures en temps constant.
[$t, $v1] = (function (string $h): array {
parse_str(str_replace(',', '&', $h), $p);
return [(int) ($p['t'] ?? 0), (string) ($p['v1'] ?? '')];
})($_SERVER['HTTP_SMSGRAB_SIGNATURE'] ?? '');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t.'.'.$body, getenv('SMSGRAB_WEBHOOK_SECRET'));
$ok = abs(time() - $t) <= 300 && hash_equals($expected, $v1);
import hmac, hashlib, time
def verify(header: str, body: bytes, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", "0"))
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
return abs(time.time() - t) <= 300 and hmac.compare_digest(expected, parts.get("v1", ""))
import crypto from 'node:crypto';
export function verify(header, rawBody, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const t = Number(parts.t ?? 0);
const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
const given = Buffer.from(parts.v1 ?? '', 'utf8');
return Math.abs(Date.now() / 1000 - t) <= 300 && given.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), given);
}
Vérifiez toujours le corps exactement tel que vous l'avez reçu, avant d'analyser le JSON.
Répondre vite
Répondez avec n'importe quel statut 2xx en moins de 10 secondes et faites le travail long ensuite, par exemple dans une file d'attente. Les redirections ne sont pas suivies.
Nouvelles tentatives
Un envoi échoué est retenté après 1 minute, 5 minutes, 15 minutes, 1 heure, 3 heures, 6 heures, 12 heures et 24 heures. Une nouvelle tentative reprend le même id d'événement : gardez la trace des identifiants traités et ignorez les doublons. Les événements d'une même activation arrivent dans l'ordre.
Désactivation automatique
- Répondre
410 Gonedésactive immédiatement le webhook. - Après 50 tentatives échouées d'affilée sur au moins 24 heures, le webhook est désactivé et vous recevez une notification. Corrigez votre point d'accès, puis réactivez le webhook.
- La révocation d'une clé désactive ses webhooks.
Tester et renvoyer
Envoyez un événement webhook.test depuis la page du webhook pour voir tout de suite le code de statut, le temps de réponse et l'éventuelle erreur. La liste des envois conserve chaque envoi pendant 30 jours, et vous pouvez renvoyer n'importe lequel.
Cet article vous a-t-il été utile ?
Merci ! Ravis que cela vous ait aidé.