Pedir orçamentoOrçamento
Automação

Webhook da iugu: como atualizar o status do pedido em tempo real

Para atualizar o status do pedido em tempo real com a iugu, cadastre um gatilho, o webhook da iugu, para o evento invoice.status_changed. Ele aponta para um endpoint do seu sistema, e a iugu envia um POST com o id e o novo status da fatura; o endpoint confere a chave, registra o aviso, responde 200 na hora e atualiza o pedido em seguida.

Atualizado em · Por Luis Henrique Cuba

Tirar minha dúvida com a LHCX

Como cadastrar o gatilho

  1. Pelo painel

    Em Configurações > Integrações > Comunicação via Gatilho: escolha o evento, informe a URL e salve.

  2. Pela API

    POST https://api.iugu.com/v1/web_hooks com event, url e authorization. GET /v1/web_hooks/supported_events lista os eventos disponíveis. A documentação cita o limite de 20 gatilhos por conta.

  3. Um cadastro por ambiente

    Teste e produção são isolados: o gatilho do ambiente de teste não recebe eventos de produção, e vice-versa.

Eventos de fatura que interessam ao pedido

  1. invoice.status_changed

    O principal: avisa toda mudança de status (paid, canceled, partially_paid, refunded, expired, externally_paid, in_protest, chargeback, entre outros).

  2. invoice.created

    A fatura foi criada. Traz data[source], que diz a origem: api, alia (o painel), payment_booklet ou subscription.

  3. invoice.payment_failed

    Tentativa de pagamento que falhou, útil para avisar o cliente.

  4. invoice.refund e invoice.due

    Reembolso da fatura e data de vencimento atingida.

  5. invoice.released e invoice.installment_released

    Liberação de valores. Segundo a documentação, só disparam em produção.

O que chega no seu endpoint

A iugu envia um POST com Content-Type application/x-www-form-urlencoded, como um formulário, e não em JSON. No invoice.status_changed, os campos mais usados são:

event=invoice.status_changed
data[id]=1757E1D7FD5E410A9C563024250015BF
data[status]=paid
data[payment_method]=iugu_pix
data[paid_at]=2022-03-21T11:07:36.667Z
data[paid_cents]=100
data[order_id]=N77579_31658163
data[external_reference]=N55548889
Valores dos exemplos da documentação da iugu. O aviso também traz data[account_id], data[subscription_id], data[payer_cpf_cnpj] e data[pix_end_to_end_id], entre outros.

Retentativas e reenvio

  • Sem resposta de sucesso ou com timeout, o aviso entra na lista de retentativa
  • Da 1ª à 5ª tentativa: a cada 2 segundos
  • Da 6ª à 25ª: a cada 10 segundos
  • Da 26ª à 40ª: a cada 2 minutos
  • Reenvio manual pelo painel, em Configurações > Logs de gatilhos > Reenviar
  • Reenvio pela API: GET /v1/web_hook_logs/{id}/retry para um aviso, ou GET /v1/web_hooks/resend com initial_date, final_date e event para um período (a documentação cita intervalos de 3 dias)

Endpoint mínimo em Node.js (Express)

import express from 'express';

const app = express();
// A iugu envia form-urlencoded; com extended: true, data[id] vira req.body.data.id
app.use(express.urlencoded({ extended: true }));

app.post('/webhooks/iugu', async (req, res) => {
  // Confira a chave gravada no campo authorization do gatilho
  if (req.get('authorization') !== process.env.IUGU_WEBHOOK_AUTH) return res.sendStatus(401);

  const { event, data } = req.body;
  await fila.salvar({ event, faturaId: data.id, status: data.status, pedidoId: data.order_id });
  res.sendStatus(200); // responde já; o pedido é atualizado por outro processo
});

app.listen(3000);
fila.salvar é um exemplo: pode ser uma tabela no banco, uma fila ou uma planilha. Faça um teste com um evento real para ver como o cabeçalho de autorização chega e ajuste a comparação.

Processamento: confirmar o status e não duplicar

const auth = 'Basic ' + Buffer.from(process.env.IUGU_API_TOKEN + ':').toString('base64');

async function processar(aviso) {
  const chave = aviso.faturaId + ':' + aviso.status;
  if (await jaProcessado(chave)) return; // a iugu pode reenviar o mesmo aviso

  // Confirma na API antes de mexer no pedido
  const resp = await fetch('https://api.iugu.com/v1/invoices/' + aviso.faturaId, {
    headers: { Authorization: auth }
  });
  const fatura = await resp.json();

  await atualizarPedido(fatura.order_id, fatura.status);
  await marcarProcessado(chave);
}
Consultar a fatura antes de liberar o pedido é uma prática da LHCX, não uma exigência da documentação da iugu. Ela evita agir sobre um aviso que não veio da iugu.

Status da iugu e status do pedido

Status na iuguSugestão para o pedido
pendingAguardando pagamento
paidPago: liberar separação ou acesso
partially_paidPendência financeira
expiredExpirado: oferecer nova cobrança
canceledCancelado
refundedReembolsado
in_protestEm disputa: segurar o envio
chargebackEstornado
externally_paidPago fora da iugu: conferir o comprovante
Sugestão da LHCX. Os significados de cada status estão na página Status da documentação da iugu.

Erros comuns

  1. Endpoint que lê JSON

    O aviso chega como formulário. Um endpoint que só entende JSON recebe o corpo vazio.

  2. Processar tudo antes de responder

    Se o processamento demora, a iugu considera falha e reenvia. Responda 200 e processe depois.

  3. Pedido liberado duas vezes

    Falta de controle de repetição. Use o id da fatura com o status como chave.

  4. Gatilho cadastrado só em teste

    Os ambientes são isolados. Cadastre o gatilho também em produção, com a URL de produção.

  5. Firewall bloqueando a iugu

    A documentação informa o IP de saída 98.82.243.132, que substituiu o 54.207.210.151 em 04/08/2025. Regras antigas de firewall bloqueiam os avisos.

Leituras relacionadas

  1. Integração com a iugu

    A LHCX monta a cobrança pela API e o status pelos gatilhos, com logs e reprocessamento.

    Ver a página

  2. Integração da iugu com o Omie

    O aviso de pagamento vira baixa no contas a receber do Omie.

    Ver a página

  3. Webhooks avançados

    Filas, idempotência e arquitetura orientada a eventos.

    Ver a página
Perguntas frequentes

Webhook da iugu: como atualizar o status do pedido em tempo real: dúvidas comuns

O webhook da iugu tem assinatura para validar a origem?

Na documentação que consultamos, não encontramos assinatura do conteúdo do aviso. O que existe é o campo authorization do gatilho, uma chave usada como Basic Authentication na validação do recebimento. Por isso vale confirmar o status consultando a fatura pela API.

Qual a diferença entre o gatilho e a notification_url?

O gatilho é cadastrado na conta, por evento, e vale para todas as faturas. A notification_url é informada na criação de uma fatura e manda as notificações daquela fatura para um endereço diferente.

Quantas vezes a iugu tenta entregar o aviso?

Até 40 vezes: 5 a cada 2 segundos, 20 a cada 10 segundos e 15 a cada 2 minutos. Depois disso, o reenvio pode ser feito pelo painel ou pela API.

Dá para receber o webhook da iugu no n8n?

Dá. Um nó Webhook com método POST recebe o formulário da iugu. O restante segue a mesma lógica: conferir a chave, registrar, responder e processar sem duplicar.

Perdi avisos enquanto o sistema estava fora. E agora?

Use o reenvio por período (GET /v1/web_hooks/resend) ou o reenvio pelos logs no painel. Como o endpoint é idempotente, avisos já processados são ignorados.

Perguntas parecidas

Mais sobre automação

Precisa de ajuda para resolver isso na sua empresa?

Respondemos em até 24 horas com as próximas perguntas e uma proposta objetiva.

Pedir orçamentoEscrever por e-mail