Webhook notifications

Add webhook subscriber

Login to your status page at instatus.com/login then choose your status page.

Click on the subscribers tab, then Webhook.

Click Add webhook subscriber,

A new form will appear where you can enter:

• Webhook URL
• Email address

We will send a requests to your URL using this format and an email will be sent to the specified email address when there is an issue with the URL.

You can give a name to your webhook subscriber by clicking on it and typing a name in the form, you could also delete this subscriber by clicking Unsubscribe.

Webhook Payload Verification

It is Highly recommended to validate the webhook payload in the webhook endpoint.

We sign webhook payloads with a secret and include the signature as a header named x-instatus-webhook-signature. This signature allows you to verify the webhook came from Instatus.

Steps To Verify Webhook

1. Retrieve your Webhook Secret from the dashboard (You can find it while editing or creating a webhook, you can also customize it there).

2. Create a new endpoint on your server that will receive the webhook.

3. Compare the signature with your server's generated signature to validate.

4. If the signatures match, process the webhook.

Code Example

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

Why Verification Matters

• Ensures Authenticity: Guarantees that the webhook originates from our platform.
• Prevents Tampering: Detects changes to the payload.
• Improves Security: Protects against replay attacks and unauthorized access.