Notificações por webhook

Adicionar assinante de webhook

Entre na Instatus em instatus.com/login e escolha sua página de status.

Vá em Assinantes e depois em Webhook.

Clique em Adicionar assinante de webhook,

Um novo formulário aparece, onde você informa:

• A URL do webhook
• O endereço de e-mail

Enviaremos requisições para sua URL neste formato e um e-mail será enviado ao endereço informado quando houver algum problema com a URL.

Você pode dar um nome ao assinante de webhook clicando nele e digitando o nome no formulário. Também dá para excluir esse assinante clicando em Cancelar inscrição.

Verificação do payload do webhook

É altamente recomendável validar o payload do webhook no endpoint que o recebe.

Assinamos os payloads dos webhooks com um segredo e enviamos a assinatura em um cabeçalho chamado x-instatus-webhook-signature. Essa assinatura permite verificar que o webhook veio da Instatus.

Passos para verificar o webhook

1. Pegue o seu segredo do webhook no painel (ele aparece ao criar ou editar um webhook, e lá também dá para personalizá-lo).

2. Crie um novo endpoint no seu servidor para receber o webhook.

3. Compare a assinatura recebida com a assinatura gerada pelo seu servidor para validar.

4. Se as assinaturas forem iguais, processe o webhook.

Exemplo 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 que a verificação importa

• Garante autenticidade: assegura que o webhook veio da nossa plataforma.
• Impede adulteração: detecta alterações no payload.
• Aumenta a segurança: protege contra ataques de repetição e acessos não autorizados.