Formato de los webhooks

Este es el formato de los webhooks que recibirás si te has suscrito por webhook:

Cuando se añade o se actualiza una incidencia:

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

Cuando se añade o se actualiza un mantenimiento:

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

Cuando se actualiza un componente:

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

Estados posibles de la página de estado:

UP
HASISSUES
UNDERMAINTENANCE

Estados posibles de un componente:

OPERATIONAL
UNDERMAINTENANCE
DEGRADEDPERFORMANCE
PARTIALOUTAGE
MAJOROUTAGE

Estados posibles de una incidencia:

INVESTIGATING
IDENTIFIED
MONITORING
RESOLVED

Estados posibles de un mantenimiento:

NOTSTARTEDYET
INPROGRESS
COMPLETED

Verificación de la carga del webhook

Recomendamos encarecidamente validar la carga del webhook en tu endpoint.

Firmamos las cargas de los webhooks con un secreto e incluimos la firma en una cabecera llamada x-instatus-webhook-signature. Esa firma te permite verificar que el webhook viene de Instatus.

Pasos para verificar un webhook

Guarda el secreto del webhook que generaste al suscribirte (lo encontrarás al suscribir un webhook a una página, y también puedes personalizarlo ahí).

Crea un endpoint nuevo en tu servidor que reciba el webhook.
Compara la firma con la que genere tu servidor para validarla.
Si las firmas coinciden, procesa el webhook.

Ejemplo de código

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

Por qué importa la verificación

Garantiza la autenticidad: confirma que el webhook procede de nuestra plataforma.
Evita manipulaciones: detecta cambios en la carga.
Mejora la seguridad: protege frente a ataques de repetición y accesos no autorizados.