Formato dei webhook

Ecco il formato dei webhook che riceverai se ti sei iscritto tramite webhook:

Quando un incidente viene aggiunto o aggiornato:

{
  "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": ""
      }
    ]
  }
}

Quando una manutenzione viene aggiunta o aggiornata:

{
  "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": ""
      }
    ]
  }
}

Quando un componente viene aggiornato:

{
  "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": ""
  }
}

Stati possibili della status page:

UP
HASISSUES
UNDERMAINTENANCE

Stati possibili dei componenti:

OPERATIONAL
UNDERMAINTENANCE
DEGRADEDPERFORMANCE
PARTIALOUTAGE
MAJOROUTAGE

Stati possibili degli incidenti:

INVESTIGATING
IDENTIFIED
MONITORING
RESOLVED

Stati possibili delle manutenzioni:

NOTSTARTEDYET
INPROGRESS
COMPLETED

Verifica del payload del webhook

È fortemente consigliato validare il payload del webhook nel tuo endpoint.

Firmiamo i payload dei webhook con un secret e includiamo la firma in un header chiamato x-instatus-webhook-signature. Questa firma ti permette di verificare che il webhook provenga davvero da Instatus.

Passaggi per verificare un webhook

Conserva il secret del webhook che hai generato durante l'iscrizione al webhook (lo trovi quando iscrivi una pagina tramite webhook e puoi anche personalizzarlo lì).

Crea sul tuo server un nuovo endpoint che riceverà il webhook.
Confronta la firma ricevuta con quella generata dal tuo server per convalidarla.
Se le firme corrispondono, elabora il webhook.

Esempio di codice

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'))

Perché la verifica è importante

Garantisce l'autenticità: conferma che il webhook proviene dalla nostra piattaforma.
Impedisce le manomissioni: rileva le modifiche al payload.
Aumenta la sicurezza: protegge da attacchi replay e accessi non autorizzati.