API — Webhooks

Les endpoints Webhooks permettent de gérer les configurations webhook de vos applications et de consulter l'historique des livraisons.

Configurations Webhook

GET /apps/{pushable_key}/webhooks

Liste toutes les configurations webhook d'une application.

Requête :

GET /apps/app_pk_AbCdEfGhIjKlMnOp/webhooks
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "webhooks": [
    {
      "id": "wconf_abc123",
      "app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://example.com/webhooks/sendas",
      "events": ["email_sent", "email_failed_perm", "oauth_expired"],
      "is_active": true,
      "secret": "whsec_abc...xyz",
      "created_at": "2024-01-10T10:00:00Z",
      "last_triggered_at": "2024-01-15T10:35:00Z",
      "success_rate_7d": 0.98
    }
  ]
}

POST /apps/{pushable_key}/webhooks

Crée une nouvelle configuration webhook pour une application.

Requête :

POST /apps/app_pk_AbCdEfGhIjKlMnOp/webhooks
X-Api-Secret: votre_api_secret
Content-Type: application/json

Corps :

Champ	Type	Obligatoire	Description
url	string	Oui	URL HTTPS vers laquelle envoyer les webhooks
events	string[]	Oui	Liste des événements à écouter
secret	string	Non	Secret HMAC personnalisé. Si absent, un secret est généré automatiquement.
is_active	boolean	Non	Activer/désactiver. Défaut : true

{
  "url": "https://example.com/webhooks/sendas",
  "events": [
    "email_sent",
    "email_failed_temp",
    "email_failed_perm",
    "oauth_connected",
    "oauth_expired"
  ],
  "is_active": true
}

Réponse 201 :

{
  "id": "wconf_abc123",
  "app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://example.com/webhooks/sendas",
  "events": ["email_sent", "email_failed_temp", "email_failed_perm", "oauth_connected", "oauth_expired"],
  "is_active": true,
  "secret": "whsec_GeneratedSecretXxYyZz123456",
  "created_at": "2024-01-15T12:00:00Z"
}

Conserver le secret

Le secret HMAC est affiché une seule fois lors de la création. Conservez-le pour vérifier les signatures des webhooks. Si vous le perdez, supprimez et recréez la configuration webhook.

PUT /apps/{pushable_key}/webhooks/{webhook_id}

Modifie une configuration webhook existante.

Requête :

PUT /apps/app_pk_AbCdEfGhIjKlMnOp/webhooks/wconf_abc123
X-Api-Secret: votre_api_secret
Content-Type: application/json

Corps :

{
  "url": "https://example.com/webhooks/sendas/v2",
  "events": ["email_sent", "email_failed_perm"],
  "is_active": true
}

Réponse 200 :

{
  "id": "wconf_abc123",
  "url": "https://example.com/webhooks/sendas/v2",
  "events": ["email_sent", "email_failed_perm"],
  "is_active": true,
  "updated_at": "2024-01-15T13:00:00Z"
}

DELETE /apps/{pushable_key}/webhooks/{webhook_id}

Supprime une configuration webhook.

Requête :

DELETE /apps/app_pk_AbCdEfGhIjKlMnOp/webhooks/wconf_abc123
X-Api-Secret: votre_api_secret

Réponse 204 : (aucun corps)

POST /apps/{pushable_key}/webhooks/{webhook_id}/test

Envoie un webhook de test avec un payload d'exemple.

Requête :

POST /apps/app_pk_AbCdEfGhIjKlMnOp/webhooks/wconf_abc123/test
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "success": true,
  "http_status": 200,
  "response_body": "OK",
  "duration_ms": 145,
  "payload_sent": {
    "event": "test",
    "app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2024-01-15T13:05:00Z",
    "data": {
      "message": "Ceci est un webhook de test SendAs.me"
    }
  }
}

Historique des livraisons

GET /apps/{pushable_key}/webhooks/{webhook_id}/deliveries

Liste l'historique des tentatives de livraison d'un webhook.

Requête :

GET /apps/app_pk_AbCdEfGhIjKlMnOp/webhooks/wconf_abc123/deliveries?limit=20
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "deliveries": [
    {
      "id": "wdel_1a2b3c",
      "webhook_config_id": "wconf_abc123",
      "event": "email_sent",
      "attempt_number": 1,
      "http_status": 200,
      "response_body": "OK",
      "delivered_at": "2024-01-15T10:35:23.100Z",
      "duration_ms": 145,
      "success": true,
      "error_message": null
    },
    {
      "id": "wdel_4d5e6f",
      "webhook_config_id": "wconf_abc123",
      "event": "email_sent",
      "attempt_number": 1,
      "http_status": 503,
      "response_body": "Service Unavailable",
      "delivered_at": "2024-01-14T09:12:00.000Z",
      "duration_ms": 30000,
      "success": false,
      "error_message": "HTTP 503 from endpoint"
    },
    {
      "id": "wdel_7g8h9i",
      "webhook_config_id": "wconf_abc123",
      "event": "email_sent",
      "attempt_number": 2,
      "http_status": 200,
      "response_body": "OK",
      "delivered_at": "2024-01-14T09:17:00.000Z",
      "duration_ms": 98,
      "success": true,
      "error_message": null
    }
  ],
  "total": 47,
  "success_count": 45,
  "failure_count": 2
}

Référence des événements

Événement	Description	Données incluses
email_sent	E-mail envoyé avec succès	log_id, from_address, to_address, subject, plugin, message_id
email_failed_temp	Échec temporaire	log_id, from_address, to_address, subject, plugin, error, retry_count, next_retry_at
email_failed_perm	Échec permanent	log_id, from_address, to_address, subject, plugin, error, final
oauth_connected	Compte OAuth connecté	credential_id, email, plugin, scopes
oauth_expired	Token OAuth expiré/révoqué	credential_id, email, plugin, reason