À quoi servent les webhooks ?
MsgFlash peut envoyer des requêtes HTTP signées à votre application à chaque événement important :
instance.connectedinstance.disconnectedmessage.sentmessage.deliveredmessage.readmessage.failedmessage.received
Gérer vos endpoints via l’API publique
Paramètres
POST /api/v1/webhooks
| Champ | Type | Requis | Emplacement | Description |
|---|
url | string | oui | body | URL HTTPS de réception |
events | string[] | oui | body | 1 à 50 événements |
DELETE /api/v1/webhooks/{id}
| Paramètre | Type | Requis | Emplacement | Description |
|---|
id | UUID | oui | path | ID du webhook |
Lister
curl https://srv.msgflash.com/api/v1/webhooks \
-H "x-api-key: msgf_live_your_api_key_here"
Créer
curl -X POST https://srv.msgflash.com/api/v1/webhooks \
-H "x-api-key: msgf_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/msgflash",
"events": ["message.delivered", "message.failed", "message.read"]
}'
{
"data": {
"id": "wh_uuid",
"url": "https://example.com/webhooks/msgflash",
"events": ["message.delivered", "message.failed", "message.read"],
"secret": "generated_once_secret",
"createdAt": "2026-04-01T10:00:00.000Z"
}
}
Le secret doit être conservé immédiatement. Il sert à vérifier la signature HMAC.
Supprimer
curl -X DELETE https://srv.msgflash.com/api/v1/webhooks/WEBHOOK_ID \
-H "x-api-key: msgf_live_your_api_key_here"
Erreurs courantes
| Code | HTTP | Quand |
|---|
WEBHOOKS_NOT_AVAILABLE_ON_PLAN | 403 | Feature non disponible |
MAX_WEBHOOK_ENDPOINTS_REACHED | 403 | Limite atteinte |
NOT_FOUND | 404 | Webhook introuvable |
| Header | Description |
|---|
Content-Type: application/json | Payload JSON |
X-MsgFlash-Signature | Signature sha256=<hex> |
X-MsgFlash-Event | Nom de l’événement |
Exemple de payload
{
"event": "message.delivered",
"instanceId": "inst_uuid",
"messageId": "msg_uuid",
"providerMessageId": "BAE5D1A2B3C4D5E6",
"to": "+22912345678",
"status": "delivered",
"timestamp": "2026-04-01T10:00:05.000Z"
}
Vérifier la signature
Algorithme : HMAC-SHA256(secret, rawBody)
import crypto from 'crypto'
import express from 'express'
const app = express()
app.post('/webhooks/msgflash', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-msgflash-signature'] as string
const secret = process.env.MSGFLASH_WEBHOOK_SECRET!
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex')
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature')
}
res.sendStatus(200)
})
import hmac
import hashlib
import os
WEBHOOK_SECRET = os.environ["MSGFLASH_WEBHOOK_SECRET"]
def verify(signature: str, raw_body: bytes) -> bool:
expected = "sha256=" + hmac.new(
WEBHOOK_SECRET.encode("utf-8"),
raw_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
Livraison et retry
- 5 tentatives
- backoff exponentiel
- toute réponse non-2xx déclenche un retry
Répondez 200 rapidement puis traitez en asynchrone.