Notificações Webhook

Use webhooks para receber em sua aplicação os resultados de envio de QR codes e de renovações.

O que é um webhook?

A iRoamly envia notificações de webhook com os resultados de envio de QR codes e de renovações. Cada webhook usa HTTPS e inclui um payload JSON. Use webhooks para:

• Receber as informações do QR code após a conversão de um código de resgate ou a conclusão de uma compra direta de QR code.
• Receber os resultados de renovação via webhook: esim.renewal.success quando o QR code da renovação estiver pronto, esim.renewal.failed quando o pedido de renovação no fornecedor falhar.

Se seu endpoint não responder com um status 2xx, a iRoamly faz até 5 tentativas de entrega no total: a primeira imediatamente e as demais após 30 segundos, 2 minutos, 3 minutos e 5 minutos.

Passos para receber um webhook

Você pode começar a receber eventos em tempo real no seu app seguindo estes passos:

• Crie um endpoint local para receber requisições
• Registre seu endpoint de webhook em Desenvolvedores > Notificações Webhook no Painel da iRoamly Shop

1. Crie um endpoint local para receber requisições

Na sua aplicação local, crie uma nova rota que aceite requisições POST.

Por exemplo, você pode adicionar uma rota de API no Next.js:

import type { NextApiRequest, NextApiResponse } from 'next';

export default (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {
    const payload = req.body;
    console.log(payload);
    res.status(200);
  }
};

Ao receber um evento, responda com HTTP 200 OK para sinalizar à iRoamly que o evento foi entregue com sucesso.

2. Registre seu endpoint de webhook de desenvolvimento

Registre sua URL HTTPS de acesso público no Painel da iRoamly Shop.

Você pode criar um túnel para seu servidor localhost com uma ferramenta como o ngrok.

3. Teste se seu endpoint de webhook está funcionando corretamente

Converta um código de resgate de teste em QR code, ou faça uma compra direta de QR code, para verificar se seu endpoint de webhook recebe o evento.

Lista dos tipos de evento compatíveis e seus payloads.

Entrega

Todos os eventos são entregues da mesma forma: uma requisição POST com corpo JSON para cada endpoint inscrito no evento. Qualquer resposta 2xx conta como entregue; caso contrário, há novas tentativas, até 5 no total (a primeira imediatamente e as demais após 30 segundos, 2 minutos, 3 minutos e 5 minutos). Cada requisição inclui estes headers:

Veja Verificar requisições de webhook para saber como conferir as assinaturas.

esim.qrcode

Informações do QR code da eSIM retornadas após o resgate ou a compra do QR code da eSIM.

Exemplo de corpo da requisição

{
	"code": 0,
	"data": {
		"activation_code": "CD112885573C49DDA42F64C905B925F4",
		"code": "UtTpoKCe769u2tt",
		"create_at": "2025-09-01 11:34:30",
		"isrenew": 0,
		"order_id": "ESIM202509021134343282",
		"plan_name": "Japan-eSIM-3GB-15 Days-Daily",
		"qrcode": "https://www.iroamly.com/qrcode/20250901/xSQfryvOWo0QUhsGcbpeTm9wWYfGu9BQ.png",
		"qrcode_content": "LPA:1$rsp1.cmlink.com$CD352885573C49DDA42F64C905B925F4",
		"sm_dp_address": "rsp1.cmlink.com"
	},
	"event_type": "esim.qrcode"
	}

Enviado quando uma renovação é concluída: assim que o fornecedor retorna os dados de download do pedido de renovação, o QR code do código de renovação é gerado e seu status passa a ser 2 (Resgatado).

Headers da requisição

A requisição também inclui X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature e X-Webhook-Signature-V2, como todos os eventos (veja Tipos de evento).

Exemplo de corpo da requisição

{
	"code": 0,
	"data": {
		"activation_code": "CD112885573C49DDA42F64C905B925F4",
		"code": "RnB7xTq2Lm9pQaZ",
		"create_at": "2026-10-28 09:12:41",
		"download_url": "LPA:1$rsp1.cmlink.com$CD352885573C49DDA42F64C905B925F4",
		"iccid": "8944501234567890123",
		"iscouldrenewal": 1,
		"isrenew": 1,
		"plan_name": "Japan-eSIM-3GB-15 Days-Daily",
		"qrcode": "https://www.iroamly.com/qrcode/20261028/xSQfryvOWo0QUhsGcbpeTm9wWYfGu9BQ.png",
		"qrcode_content": "LPA:1$rsp1.cmlink.com$CD352885573C49DDA42F64C905B925F4",
		"renew_order_id": "TG202610280912410001",
		"renewal_father_code": "UtTpoKCe769u2tt",
		"sm_dp_address": "rsp1.cmlink.com"
	},
	"event_type": "esim.renewal.success"
}

Campos

Enviado quando uma renovação falha: o fornecedor responde ao pedido de renovação com um código diferente de 0000, ou a requisição ao fornecedor falha.

(Observação: um callback ausente ou atrasado do fornecedor não dispara este evento. Defina um tempo limite e, como alternativa, consulte o código — veja Tratamento de eventos de renovação.)

Headers da requisição

A requisição também inclui X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature e X-Webhook-Signature-V2, como todos os eventos (veja Tipos de evento).

Exemplo de corpo da requisição

{
	"code": -1,
	"data": {
		"code": "RnB7xTq2Lm9pQaZ",
		"create_at": "2026-10-28 09:12:41",
		"error_msg": "TuGe_RenewOrderEx RespCode: 9999",
		"isrenew": 1,
		"plan_name": "Japan-eSIM-3GB-15 Days-Daily",
		"renewal_father_code": "UtTpoKCe769u2tt"
	},
	"event_type": "esim.renewal.failed"
}

Campos

As renovações não são mais entregues como esim.qrcode; esse evento é enviado para conversões em QR code e compras diretas de QR code. Em comparação com o payload de esim.qrcode:

• event_type e o header X-Webhook-Event são esim.renewal.success ou esim.renewal.failed, e isrenew é 1.
• data.code é o novo código de resgate criado pela renovação; o código que foi renovado é data.renewal_father_code.
• esim.renewal.success adiciona renew_order_id, renewal_father_code, iscouldrenewal, download_url e iccid, e não tem order_id.
• Uma renovação com falha é informada por esim.renewal.failed, com code de nível superior -1 e o erro do fornecedor em data.error_msg.

Novos endpoints são inscritos nos três eventos por padrão. Endpoints existentes recebem esim.renewal.success e esim.renewal.failed automaticamente — nenhuma alteração é necessária.

• Torne seu handler idempotente. Uma nova tentativa pode entregar o mesmo evento mais de uma vez; por isso, elimine duplicatas por X-Webhook-Delivery ou por event_type + data.code e ignore os eventos já processados.
• Use um tempo limite como alternativa. Se nem esim.renewal.success nem esim.renewal.failed chegar em um prazo razoável, consulte o código pela API de consulta (por exemplo, Consultar QR code) em vez de presumir que a renovação falhou.
• Não use esim.renewal.failed para decidir reembolsos. Ele informa apenas que o pedido no fornecedor falhou; se e quando os créditos serão devolvidos é decidido à parte, portanto não reembolse seus clientes com base neste evento.

Verifique a assinatura da iRoamly nas requisições de webhook.

Como verificar a assinatura da iRoamly?

A assinatura da iRoamly é enviada no header X-Webhook-Signature da requisição de webhook, como sha256= seguido da assinatura em hexadecimal. A assinatura é gerada com o algoritmo HMAC-SHA256, usando o segredo do webhook como chave e o corpo bruto da requisição (exatamente como recebido, antes de qualquer parsing de JSON) como mensagem.

Exemplo de header de webhook

{
'X-Webhook-Signature': 'sha256=dd7bdd2cf1f6bac6e171c6c508c157b7cd3cc1fd196394277fb59ba0bdd9b87b'
}

Você encontra o segredo do webhook em Desenvolvedores > Notificações Webhook no Painel.

Para gerar a assinatura, você pode usar o seguinte trecho de código:

import * as crypto from 'crypto';

  generateSignature(payload: string, secret: string): string {
    const computedSignature = crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
    return 'sha256=' + computedSignature;
  }

No trecho de código acima, payload é o corpo bruto da requisição e secret é o segredo do webhook. Basta comparar a assinatura gerada (incluindo o prefixo sha256=) com o valor do header X-Webhook-Signature para concluir a verificação.

Assinatura com timestamp (X-Webhook-Signature-V2)

Cada requisição também inclui X-Webhook-Signature-V2: v1= seguido do HMAC-SHA256 em hexadecimal, com o mesmo segredo do webhook, de {timestamp}.{body} — o valor do header X-Webhook-Timestamp, um ponto e o corpo bruto da requisição.

Depois que você faz a rotação do segredo do webhook, o segredo antigo continua válido por 24 horas. Durante esse período, X-Webhook-Signature continua sendo assinado com o segredo antigo, e X-Webhook-Signature-V2 contém um valor por segredo, separados por vírgulas (v1=<old>,v1=<new>): aceite a requisição se qualquer valor corresponder.