Webhooks

Lister les webhooks enregistrés

Réponses

• 200Tous les points de terminaison du compte, du plus récent au plus ancien. Sans pagination.›

  Champ	Type	Description
  data[]obligatoire	object[]
  idobligatoire	string
  urlobligatoire	string
  eventsobligatoire	string[]
  activeobligatoire	boolean
  deactivated_reasonobligatoire	string	Raison pour laquelle la livraison a désactivé le point de terminaison, le cas échéant : par exemple "HTTP_401 for 26h across 7 events" après 24 heures d’échecs sur au moins 5 événements, ou SSRF_BLOCKED. Peut être null
  deactivated_atobligatoire	string	Format : date-time Peut être null
  failing_sinceobligatoire	string	La première tentative échouée depuis la dernière livraison réussie ; null tant que le point de terminaison fonctionne normalement. Toute tentative livrée la réinitialise. Format : date-time Peut être null
  failed_eventsobligatoire	integer	Nombre d’événements distincts en échec depuis failing_since. Le point de terminaison est désactivé lorsque toutes les tentatives échouent depuis 24 heures et que ce nombre atteint 5.
  last_success_atobligatoire	string	La dernière tentative livrée, à la minute près. Format : date-time Peut être null
  last_failure_atobligatoire	string	Format : date-time Peut être null
  last_failure_reasonobligatoire	string	Le résultat de la dernière tentative échouée : HTTP_<status>, HTTP_<status>_REDIRECT_NOT_FOLLOWED, TIMEOUT ou NETWORK_ERROR. Peut être null
  secret_rotated_atobligatoire	string	Moment du dernier renouvellement du secret de signature (POST /v1/webhooks/{id}/rotate-secret) ; null tant que le point de terminaison signe encore avec le secret attribué à sa création. Format : date-time Peut être null
  created_atobligatoire	string	Format : date-time
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.webhooks.list()
if (error) throw new Error(error.message)
for (const w of data.data) console.log(w.id, w.url)

curl https://api.honkio.ca/v1/webhooks \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Enregistrer un point de terminaison de webhook

Corps de la requête

Réponses

• 201Le point de terminaison. signing_secret n’est affiché qu’ici : conservez-le pour vérifier X-HonkIO-Signature.›

  Champ	Type	Description
  idobligatoire	string
  urlobligatoire	string
  eventsobligatoire	string[]
  signing_secretobligatoire	string	64 caractères hexadécimaux.
  activeobligatoire	boolean
  created_atobligatoire	string	Format : date-time
  noticeobligatoire	string
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 422VALIDATION_ERROR (URL qui n’est pas une URL HTTPS publique, événement inconnu, ou événement courriel alors que le courriel est désactivé) ou WEBHOOK_LIMIT_REACHED (10 points de terminaison par compte).Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data: webhook, error } = await honkio.webhooks.create({
  url: 'https://yourapp.ca/webhooks/honkio',
  events: ['message.delivered', 'message.failed', 'message.received'],
})
if (error) throw new Error(error.message)
console.log(webhook.signing_secret) // shown once: store it now

curl -X POST https://api.honkio.ca/v1/webhooks \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/honkio",
    "events": [
      "message.queued"
    ]
  }'

Obtenir un webhook par identifiant

Paramètres

Réponses

• 200Le point de terminaison.›

  Champ	Type	Description
  idobligatoire	string
  urlobligatoire	string
  eventsobligatoire	string[]
  activeobligatoire	boolean
  deactivated_reasonobligatoire	string	Raison pour laquelle la livraison a désactivé le point de terminaison, le cas échéant : par exemple "HTTP_401 for 26h across 7 events" après 24 heures d’échecs sur au moins 5 événements, ou SSRF_BLOCKED. Peut être null
  deactivated_atobligatoire	string	Format : date-time Peut être null
  failing_sinceobligatoire	string	La première tentative échouée depuis la dernière livraison réussie ; null tant que le point de terminaison fonctionne normalement. Toute tentative livrée la réinitialise. Format : date-time Peut être null
  failed_eventsobligatoire	integer	Nombre d’événements distincts en échec depuis failing_since. Le point de terminaison est désactivé lorsque toutes les tentatives échouent depuis 24 heures et que ce nombre atteint 5.
  last_success_atobligatoire	string	La dernière tentative livrée, à la minute près. Format : date-time Peut être null
  last_failure_atobligatoire	string	Format : date-time Peut être null
  last_failure_reasonobligatoire	string	Le résultat de la dernière tentative échouée : HTTP_<status>, HTTP_<status>_REDIRECT_NOT_FOLLOWED, TIMEOUT ou NETWORK_ERROR. Peut être null
  secret_rotated_atobligatoire	string	Moment du dernier renouvellement du secret de signature (POST /v1/webhooks/{id}/rotate-secret) ; null tant que le point de terminaison signe encore avec le secret attribué à sa création. Format : date-time Peut être null
  created_atobligatoire	string	Format : date-time
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.webhooks.get('WEBHOOK_ID')
if (error) throw new Error(error.message)
console.log(data.url, data.events)

curl https://api.honkio.ca/v1/webhooks/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Mettre à jour un webhook

Paramètres

Corps de la requête

Réponses

• 200Le point de terminaison mis à jour.›

  Champ	Type	Description
  idobligatoire	string
  urlobligatoire	string
  eventsobligatoire	string[]
  activeobligatoire	boolean
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 422VALIDATION_ERROR : URL qui n’est pas une URL HTTPS publique, événement inconnu, ou événement courriel alors que le courriel est désactivé.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { error } = await honkio.webhooks.update('WEBHOOK_ID', { events: ['message.delivered', 'message.failed'] })
if (error) throw new Error(error.message)

curl -X PATCH https://api.honkio.ca/v1/webhooks/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "message.delivered",
      "message.failed"
    ]
  }'

Supprimer un webhook

Paramètres

Réponses

• 204Supprimé, avec son historique de livraison et ses lettres mortes.
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { error } = await honkio.webhooks.remove('WEBHOOK_ID')
if (error) throw new Error(error.message)

curl -X DELETE https://api.honkio.ca/v1/webhooks/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Lister les tentatives de livraison récentes d’un webhook

Paramètres

Réponses

• 200Tentatives de livraison récentes, de la plus récente à la plus ancienne.›

  Champ	Type	Description
  data[]obligatoire	object[]
  idobligatoire	string
  event_idobligatoire	string
  event_typeobligatoire	string
  attemptobligatoire	integer
  successobligatoire	boolean
  http_statusobligatoire	integer	Peut être null
  error_reasonobligatoire	string	Peut être null
  duration_msobligatoire	integer	Peut être null
  occurred_atobligatoire	string	Format : date-time
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.webhooks.deliveries('WEBHOOK_ID', { limit: 20 })
if (error) throw new Error(error.message)
console.log(data.data)

curl https://api.honkio.ca/v1/webhooks/ID/deliveries \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Lister les événements dont toutes les tentatives de livraison ont échoué (file des lettres mortes)

Paramètres

Réponses

• 200Événements dont toutes les tentatives ont échoué, du plus récent au plus ancien.›

  Champ	Type	Description
  data[]obligatoire	object[]
  idobligatoire	string
  event_idobligatoire	string
  event_typeobligatoire	string
  failed_reasonobligatoire	string	Raison pour laquelle l’événement n’est plus réessayé : l’échec de la dernière tentative, avec le nombre de tentatives, après environ 24 heures de nouvelles tentatives (par exemple "HTTP_500 after 8 attempts"), la même valeur suivie de "; endpoint disabled" lorsque le point de terminaison a été désactivé alors que l’événement lui était dû, ENDPOINT_DISABLED lorsque vous aviez vous-même désactivé le point de terminaison, SSRF_BLOCKED ou queue_full.
  created_atobligatoire	string	Format : date-time
  replayed_atobligatoire	string	Format : date-time Peut être null
  payloadobligatoire	any	Le corps de l’événement dont la livraison a échoué : { id, type, created, account_id, data }.
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.webhooks.deadLetters('WEBHOOK_ID')
if (error) throw new Error(error.message)
for (const dl of data.data) console.log(dl.id)

curl https://api.honkio.ca/v1/webhooks/ID/dead-letters \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Relancer un événement en lettre morte vers l’URL du webhook d’origine

Paramètres

Réponses

• 200Votre point de terminaison a accepté la relance.›

  Champ	Type	Description
  statusobligatoire	string	Une valeur parmi : replayed
  http_statusobligatoire	integer	Peut être null
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 409DEAD_LETTER_ALREADY_REPLAYED : déjà relancé, ou une relance est en cours. Également ACCOUNT_SUSPENDED lorsque le compte est suspendu ou fermé. Dans les deux cas, rien n’a été envoyé.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.
• 502WEBHOOK_REPLAY_FAILED : votre point de terminaison n’a pas accepté la relance. L’événement reste dans la file des lettres mortes.›

  Champ	Type	Description
  codeobligatoire	string	Code d’erreur lisible par machine, p. ex. VALIDATION_ERROR.
  messageobligatoire	string	Message lisible dans la langue de la requête (Accept-Language).
  messageEn	string	Message en anglais, toujours fourni en plus de message.
  messageFr	string	Message en français, toujours fourni en plus de message.
  statusCodeobligatoire	integer	Le statut HTTP, repris dans le corps.
  details	any	Présent sur certaines erreurs : un tableau de validation AJV, ou des détails structurés propres à l’erreur.
  statusobligatoire	string	Une valeur parmi : failed
  http_statusobligatoire	integer	Peut être null
  error_reasonobligatoire	string	Peut être null

Exemple

const { error } = await honkio.webhooks.replay('DEAD_LETTER_ID')
if (error) throw new Error(error.message)

curl -X POST https://api.honkio.ca/v1/webhooks/dead-letters/DLID/replay \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Abandonner un événement en lettre morte sans le relancer

Paramètres

Réponses

• 204Abandonné.
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { error } = await honkio.webhooks.discard('DEAD_LETTER_ID')
if (error) throw new Error(error.message)

curl -X DELETE https://api.honkio.ca/v1/webhooks/dead-letters/DLID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Réactiver un webhook désactivé automatiquement à la suite d’échecs de livraison

Paramètres

Réponses

• 200Le point de terminaison est de nouveau actif.›

  Champ	Type	Description
  idobligatoire	string
  activeobligatoire	boolean
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 422VALIDATION_ERROR : l’URL ne se résout plus vers un point de terminaison public.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { error } = await honkio.webhooks.reactivate('WEBHOOK_ID')
if (error) throw new Error(error.message)

curl -X POST https://api.honkio.ca/v1/webhooks/ID/reactivate \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Renouveler le secret de signature d’un webhook

Paramètres

Réponses

• 200Le nouveau secret, affiché uniquement ici. L’ancien secret cesse immédiatement de signer ; les nouvelles tentatives de tout ce que le point de terminaison rejette pendant la transition sont signées de nouveau avec celui-ci.›

  Champ	Type	Description
  idobligatoire	string
  signing_secretobligatoire	string	64 caractères hexadécimaux.
  secret_rotated_atobligatoire	string	Format : date-time
  noticeobligatoire	string
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.webhooks.rotateSecret('WEBHOOK_ID')
if (error) throw new Error(error.message)
console.log(data.signing_secret) // the old secret stopped signing: store this one

curl -X POST https://api.honkio.ca/v1/webhooks/ID/rotate-secret \
  -H "Authorization: Bearer mk_live_YOUR_KEY"