Webhook sortant

En plus de l'email, de Discord, de Slack et de Telegram, PostShip peut envoyer chaque alerte en POST vers une URL HTTPS à vous, signée en HMAC-SHA256. C'est le canal des automates : ouvrir un ticket, couper un déploiement, allumer une lampe. Il obéit aux mêmes règles que les autres canaux (silence, heures calmes, confirmation, maintenance) parce qu'il reçoit exactement le même lot d'éléments, une fois filtré.

Ce que PostShip envoie

Une requête par sorte d'événement : un lot qui mêle un échec et un rétablissement devient deux requêtes, une fail et une recovered.

POST /hooks/postship HTTP/1.1
Content-Type: application/json
X-PostShip-Event: fail
X-PostShip-Signature: sha256=3f1a…e9c2

{
  "event": "fail",
  "projectId": "8b2f…",
  "projectName": "Mon site",
  "at": "2026-09-11T14:03:12.418Z",
  "items": [
    { "url": "https://monsite.fr/checkout", "httpStatus": 503, "missing": null },
    { "url": "https://monsite.fr/", "httpStatus": 200, "missing": ["asset:script:/app.js"] }
  ],
  "test": false
}

La signature

X-PostShip-Signature vaut sha256= suivi de l'empreinte HMAC-SHA256 hexadécimale du corps brut de la requête, calculée avec votre secret. Vérifiez-la avant de lire le contenu : sans elle, n'importe qui connaissant l'URL peut vous faire ouvrir un ticket.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifier(corpsBrut, signature, secret) {
  const attendue = "sha256=" + createHmac("sha256", secret).update(corpsBrut).digest("hex");
  const a = Buffer.from(attendue);
  const b = Buffer.from(signature ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Le corps doit être lu tel quel (texte brut) avant tout décodage JSON : la signature porte sur les octets envoyés, et un re-sérialisation change l'ordre des clés ou les espaces.

Ce que PostShip exige de votre endpoint

• Une URL HTTPS publique. Une adresse privée, locale ou qui résout vers un réseau interne est refusée à l'enregistrement, et de nouveau à chaque envoi.
• Une réponse 2xx en moins de 4 secondes. Au-delà, l'envoi est abandonné, sans nouvel essai.
• Pas de redirection : un 3xx n'est pas suivi, il compte comme un échec. Le corps signé ne doit pas être remis à un autre hôte que celui que vous avez déclaré.

Un endpoint qui échoue n'empêche ni les autres canaux ni le passage suivant : l'erreur est notée côté PostShip, rien d'autre.

Régler

Projet → Intégrations, carte « Webhook sortant ».

1. Collez l'URL dans « URL du webhook sortant » et enregistrez.
2. Cliquez sur « Régénérer le secret ». Le secret (64 caractères hexadécimaux) s'affiche une seule fois : « Copiez ce secret maintenant — il ne sera plus jamais affiché. » Rangez-le dans une variable d'environnement de votre côté. Tant qu'aucun secret n'existe, rien n'est envoyé.
3. Cliquez sur « Envoyer un test » : une requête fail avec un seul élément https://example.com en 500 et "test": true. Votre endpoint peut ainsi distinguer une sonde d'un vrai incident.
4. Choisissez les « Événements envoyés » : Échec, Rétablissement, Changement, DNS. Tout coché par défaut. Décocher tout est refusé : « Choisissez au moins un événement — ou désactivez le webhook. »

« Désactiver » efface l'URL et le secret. « Régénérer le secret » invalide l'ancien immédiatement.

Ce qui déclenche un envoi

Exactement ce qui déclenche une alerte sur les autres canaux, voir Email, Discord, Slack, Telegram et Règles : transition d'échec, rétablissement d'un incident signalé, contenu modifié après déploiement, dérive DNS. Les envois retenus par le silence, les heures calmes ou une maintenance ne sont pas rejoués. Le tri par événement se fait ici et nulle part ailleurs : les autres canaux reçoivent tout.

Limites et plans

Voir les plans. Pour lire l'état d'un projet plutôt que d'attendre qu'il vous écrive, voir l'API.

Dépannage

Pourquoi « Envoyer un test » répond « Configurez d'abord l'URL et générez un secret » ?

Les deux sont nécessaires : sans secret, PostShip ne signe pas, donc n'envoie pas. Cliquez sur « Régénérer le secret ».

Pourquoi la signature ne correspond jamais ?

Vous vérifiez sans doute le JSON re-sérialisé plutôt que le corps brut. Lisez le corps en texte avant JSON.parse, calculez le HMAC dessus, et comparez à la valeur après sha256=.

Pourquoi mon endpoint reçoit fail mais jamais recovered ?

Regardez les cases « Événements envoyés ». Et un rétablissement n'est envoyé que si l'échec l'avait été : voir Règles.