Webhooks

Webhooks são notificações HTTP que a Amplifique.me envia para o seu sistema quando algo acontece na plataforma. É o inverso da API: em vez de você consultar a Amplifique.me periodicamente, nós avisamos você no momento em que o evento ocorre.

Use Webhooks para registrar respostas no seu CRM em tempo real, abrir um ticket automaticamente quando um Detrator responde, ou alimentar dashboards ao vivo.

Como funciona

Eventos disponíveis

Você escolhe quais eventos cada endpoint recebe ao configurá-lo. Um endpoint só recebe os eventos que você marcou.

A requisição que você recebe

Sempre um POST com o corpo em JSON.

Como validar a assinatura

Cada webhook é assinado com o secret do seu endpoint, disponível na tela de configuração do webhook na plataforma. Valide a assinatura antes de confiar no conteúdo — é o que garante que a requisição veio realmente da Amplifique.me.

A assinatura é o HMAC-SHA256, em hexadecimal, da string formada por:

{valor do header ampl-time}.{corpo cru da requisição}

Ou seja: o timestamp, um ponto, e o body exatamente como chegou.

Node.js (Express)

const crypto = require('crypto');
const express = require('express');

const app = express();

// guarde o corpo cru para poder validar a assinatura
app.use(express.json({
  verify: (req, res, buf) => { req.rawBody = buf; }
}));

app.post('/webhooks/amplifique', (req, res) => {
  const timestamp = req.header('ampl-time');
  const received  = req.header('ampl-signature');

  const expected = crypto
    .createHmac('sha256', process.env.AMPL_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.rawBody.toString('utf8')}`, 'utf8')
    .digest('hex');

  // comparação em tempo constante evita ataques de timing
  const valid = received?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

  if (!valid) return res.status(401).send();

  // responda primeiro, processe depois
  res.status(200).send();
  processarEvento(req.body);
});

Python (Flask)

import hmac, hashlib, os
from flask import Flask, request

app = Flask(__name__)

@app.post('/webhooks/amplifique')
def amplifique_webhook():
    timestamp = request.headers.get('ampl-time', '')
    received  = request.headers.get('ampl-signature', '')

    payload  = f"{timestamp}.{request.get_data(as_text=True)}"
    expected = hmac.new(
        os.environ['AMPL_WEBHOOK_SECRET'].encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(received, expected):
        return '', 401

    processar_evento(request.get_json())
    return '', 200

O que esperamos da sua resposta

Responda o mais rápido possível e faça o processamento pesado de forma assíncrona. O limite de 20 segundos vale para o tempo total da requisição — se o seu processamento demora, você recebe entregas duplicadas por timeout, mesmo tendo processado tudo com sucesso.

Retentativas e backoff

Quando uma entrega falha, ela é reagendada automaticamente com backoff exponencial: o intervalo dobra a cada nova tentativa, começando em 1 minuto.

São até 8 tentativas por evento, distribuídas ao longo de aproximadamente 2 horas:

Se a 8ª tentativa também falhar, o evento é encerrado permanentemente e não será mais reenviado. O histórico completo de tentativas continua disponível nos logs do webhook.

Desativação automática de endpoints

Além do controle por evento, cada endpoint tem um contador de erros que mede sua saúde ao longo do tempo:

• Cada entrega que falha soma 1 ao contador
• Cada entrega bem-sucedida subtrai 1 (o contador nunca fica negativo)
• Quando o contador passa de 50, o endpoint é desativado e para de receber eventos

O contador se recupera sozinho: um endpoint que volta a funcionar vai zerando os erros acumulados a cada entrega bem-sucedida. A desativação só acontece quando as falhas superam consistentemente os sucessos.

Alertas por e-mail

Se você informou um e-mail ao configurar o webhook, enviamos um aviso quando falhas são detectadas, com link direto para a tela do webhook. Para não gerar excesso de mensagens durante uma indisponibilidade longa, há um intervalo mínimo de 4 horas entre alertas do mesmo endpoint.

Reativando um endpoint

Um endpoint desativado não volta sozinho. Corrija o problema no seu sistema e reative o webhook nas configurações da plataforma. Os eventos ocorridos enquanto ele estava desativado não são reenviados.

Logs de entrega

Na tela do webhook na plataforma você acompanha cada tentativa de entrega, com o status HTTP retornado, o corpo da resposta do seu servidor, o tempo de resposta e o horário. É o primeiro lugar para olhar quando um evento não chegou como esperado.

Boas práticas

Próximos passos