Format des webhooks

Voici le format des webhooks que vous recevrez si vous vous êtes abonné par webhook :

Lorsqu’un incident est ajouté ou mis à jour :

{
  "meta": {
    "unsubscribe": "",
    "documentation": ""
  },
  "page": {
    "id": "",
    "status_indicator": "",
    "status_description": "",
    "url": ""
  },
  "incident": {
    "backfilled": false,
    "created_at": "",
    "impact": "",
    "name": "",
    "resolved_at": "",
    "status": "",
    "updated_at": "",
    "id": "",
    "url": "",
    "incident_updates": [
      {
        "id": "",
        "incident_id": "",
        "body": "",
        "status": "",
        "created_at": "",
        "updated_at": ""
      }
    ]
  }
}

Lorsqu’une maintenance est ajoutée ou mise à jour :

{
  "meta": {
    "unsubscribe": "",
    "documentation": ""
  },
  "page": {
    "id": "",
    "status_indicator": "",
    "status_description": "",
    "url": ""
  },
  "maintenance": {
    "backfilled": false,
    "created_at": "",
    "impact": "",
    "name": "",
    "resolved_at": "",
    "status": "",
    "updated_at": "",
    "id": "",
    "url": "",
    "duration": "",
    "maintenance_updates": [
      {
        "id": "",
        "maintenance_id": "",
        "body": "",
        "status": "",
        "created_at": "",
        "updated_at": ""
      }
    ]
  }
}

Lorsqu’un composant est mis à jour :

{
  "meta": {
    "unsubscribe": "https://<status-page-domain>/unsubscribe?id=${subscriber.id}&token=${subscriber.unsubscribeToken}",
    "documentation": ""
  },
  "page": {
    "id": "",
    "status_indicator": "",
    "status_description": "",
    "url": ""
  },
  "component_update": {
    "created_at": "",
    "new_status": "",
    "component_id": ""
  },
  "component": {
    "created_at": "",
    "id": "",
    "name": "",
    "status": ""
  }
}

Statuts de page de statut possibles :

UP
HASISSUES
UNDERMAINTENANCE

Statuts de composant possibles :

OPERATIONAL
UNDERMAINTENANCE
DEGRADEDPERFORMANCE
PARTIALOUTAGE
MAJOROUTAGE

Statuts d’incident possibles :

INVESTIGATING
IDENTIFIED
MONITORING
RESOLVED

Statuts de maintenance possibles :

NOTSTARTEDYET
INPROGRESS
COMPLETED

Vérification de la charge utile du webhook

Il est fortement recommandé de valider la charge utile du webhook dans votre point de terminaison.

Nous signons les charges utiles des webhooks avec un secret et incluons la signature dans un en-tête nommé x-instatus-webhook-signature. Cette signature vous permet de vérifier que le webhook provient bien d’Instatus.

Étapes pour vérifier un webhook

Conservez le secret de webhook généré lors de votre abonnement au webhook (vous le trouvez au moment de vous abonner à une page par webhook, où vous pouvez aussi le personnaliser).

Créez sur votre serveur un point de terminaison qui recevra le webhook.
Comparez la signature avec celle générée par votre serveur pour la valider.
Si les signatures correspondent, traitez le webhook.

Exemple de code

import crypto from 'crypto'
import express from 'express'

const app = express()
app.use(express.json())

const WEBHOOK_SECRET = 'your-webhook-secret'

function isVerifiedPayload(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret)
  const digest = hmac.update(JSON.stringify(payload)).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature))
}

app.post('/endpoint/to/webhook', (req, res) => {
  const payload = req.body
  const signature = req.header('x-instatus-webhook-signature')

  if (!signature) {
    return res.status(400).send('Signature missing')
  }

  if (!isVerifiedPayload(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }

  // Process the valid webhook
  res.status(200).send('Webhook received')
})

app.listen(3000, () => console.log('Server running on port 3000'))

Pourquoi la vérification est importante

Garantit l’authenticité : assure que le webhook provient bien de notre plateforme.
Empêche l’altération : détecte toute modification de la charge utile.
Renforce la sécurité : protège contre les attaques par rejeu et les accès non autorisés.