Formaat van webhooks

Dit zijn de formaten van de webhooks die je krijgt als je je via webhooks hebt geabonneerd:

Wanneer een incident wordt toegevoegd of bijgewerkt:

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

Wanneer onderhoud wordt toegevoegd of bijgewerkt:

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

Wanneer een component wordt bijgewerkt:

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

Mogelijke statussen van de statuspagina:

UP
HASISSUES
UNDERMAINTENANCE

Mogelijke componentstatussen:

OPERATIONAL
UNDERMAINTENANCE
DEGRADEDPERFORMANCE
PARTIALOUTAGE
MAJOROUTAGE

Mogelijke incidentstatussen:

INVESTIGATING
IDENTIFIED
MONITORING
RESOLVED

Mogelijke onderhoudsstatussen:

NOTSTARTEDYET
INPROGRESS
COMPLETED

Verificatie van de webhook-payload

Het wordt sterk aangeraden om de webhook-payload in je webhook-endpoint te valideren.

We ondertekenen webhook-payloads met een secret en sturen de handtekening mee als header met de naam x-instatus-webhook-signature. Met die handtekening controleer je of de webhook echt van Instatus komt.

Stappen om een webhook te verifiëren

Bewaar het Webhook Secret dat je hebt gegenereerd toen je je op de webhook abonneerde (je vindt het terwijl je je via een webhook op een pagina abonneert, en je kunt het daar ook aanpassen).

Maak op je server een nieuw endpoint dat de webhook ontvangt.
Vergelijk de handtekening met de handtekening die je server genereert om te valideren.
Komen de handtekeningen overeen, verwerk de webhook dan.

Codevoorbeeld

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

Waarom verificatie belangrijk is

Garandeert echtheid: bevestigt dat de webhook van ons platform komt.
Voorkomt manipulatie: signaleert wijzigingen in de payload.
Verhoogt de veiligheid: beschermt tegen replay-aanvallen en ongeautoriseerde toegang.