SMSFlow

Como configurar Webhooks de SMS

Webhooks são como um "carteiro automático": quando algo acontece (SMS entregue, falhou, respondido), o SMSFlow envia uma notificação para a URL da sua aplicação em tempo real.

⏱ 5 min•Nível: Intermediário

Eventos disponíveis

sms.deliveredSMS entregue com sucesso ao destinatário
sms.failedFalha na entrega (número inválido, operadora bloqueou, etc)
sms.pendingSMS em fila aguardando envio
sms.repliedDestinatário respondeu a mensagem

Como configurar

1

Acesse Dashboard → Webhooks no menu lateral.

2

Clique em "Novo Webhook" e insira a URL do seu endpoint (deve ser HTTPS em produção).

3

Selecione quais eventos você quer receber (pode selecionar todos).

4

Copie o "Webhook Secret" gerado — você usará para verificar a assinatura HMAC.

5

Clique em "Salvar" e teste usando o botão "Enviar evento de teste".

Exemplo — Node.js (Express)

Recebendo e processando eventos de entrega

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

app.use(express.json());

app.post('/webhooks/smsflow', (req, res) => {
  // Verificar assinatura HMAC
  const signature = req.headers['x-smsflow-signature'];
  const body = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(body)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Assinatura inválida');
  }

  const { event, data } = req.body;

  if (event === 'sms.delivered') {
    console.log('SMS entregue:', data.messageId, data.to);
    // Atualizar status no seu banco de dados
  }

  if (event === 'sms.failed') {
    console.log('SMS falhou:', data.messageId, data.reason);
    // Registrar falha ou retentar
  }

  res.status(200).json({ received: true });
});

app.listen(3000);

Exemplo — PHP

<?php
$signature = $_SERVER['HTTP_X_SMSFLOW_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, getenv('WEBHOOK_SECRET'));

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Assinatura inválida');
}

$payload = json_decode($body, true);

if ($payload['event'] === 'sms.delivered') {
    // Atualizar status no banco
    $messageId = $payload['data']['messageId'];
    // UPDATE sms_logs SET status='delivered' WHERE id='$messageId'
}

http_response_code(200);
echo json_encode(['received' => true]);

Importante

  • • Seu endpoint deve responder com HTTP 200 em até 10 segundos.
  • • Em caso de falha, o SMSFlow retenta até 3 vezes com intervalo de 5 minutos.
  • • Nunca exponha seu Webhook Secret no código-fonte público.
Configurar webhooks agora