Webhooks

Webhooks são um mecanismo de comunicação entre sistemas que permite notificar clientes sobre eventos de pedidos na plataforma Minu, permitindo integração em tempo real via HTTP POST para URLs configuradas pelos clientes. Diferente de APIs tradicionais, que exigem consultas periódicas para obter dados, os Webhooks operam sob um modelo push, enviando notificações instantâneas para um endpoint configurado.

Como funciona ?

Quando um evento específico acontece em um sistema, ele dispara uma requisição HTTPS para uma URL previamente definida. Essa requisição contém um payload em formato JSON, com detalhes sobre o evento ocorrido.

Objetivo:

Garantir que clientes recebam informações consistentes e seguras sobre o status dos pedidos.
Facilitar automações de negócio e acompanhamento do ciclo de vida do pedido sem necessidade de consultas manuais.

Benefícios para o Cliente:

Atualização em tempo real sobre pedidos e recompensas.
Flexibilidade para configurar URLs por campanha ou globalmente.
Segurança com múltiplas opções de autenticação.
Confiabilidade garantida por retentativas automáticas.

Eventos Suportados

registered-requests: Acionado quando um pedido é registrado na plataforma.
- Notifica em caso de sucesso ou erro.
processed-requests: Acionado quando um pedido é processado com sucesso.

Formas de Configuração

O cliente pode escolher como receber as notificações:

Por pedido → URLs enviadas no body de cada requisição de pedido. Atualmente necessita de uma subscription para funcionar.
Por cliente → URL configurada uma única vez para todos os pedidos.
Por experiência/campanha → URLs distintas por campanha/experiência.

Rotina de Retentativa

Até 5 tentativas em caso de falha.
Intervalo de 3 horas entre cada tentativa.
Dados ficam armazenados até o sucesso da entrega ou o esgotamento das tentativas.

Observação: os dados podem ser alterados via configuração. Se necessário, as informações aqui serão atualizadas.

Requisitos para o Cliente

Disponibilizar um endpoint HTTPS com suporte a TLS 1.2 (fixo).
Responder com status HTTP 200–299 para confirmar o processamento.
Implementar tratamento de idempotência (em caso de múltiplos envios do mesmo evento).

Visão geral dos eventos

Evento	Quando dispara	Sucesso	Erro	Observações
`registered-requests`	Pedido registrado na plataforma	Sim	Sim	Notifica tanto sucesso quanto falha de registro
`processed-requests`	Pedido processado com sucesso	Sim	Não	Apenas em sucesso de processamento

Campos por evento (obrigatórios vs. condicionais)

`registered-requests`

Campo	Tipo	Obrigatório	Quando aparece	Descrição
`id`	string	Sim	Sempre	Identificador do pedido na Minu
`rewardValue`	integer	Não	Se houver recompensa	Valor da recompensa associada
`errorCode`	string	Não	Em caso de erro	Código interno de erro
`message`	string	Não	Em caso de erro	Mensagem descritiva do erro

`processed-requests`

Campo	Tipo	Obrigatório	Quando aparece	Descrição
`id`	string	Sim	Sempre	Identificador do pedido na Minu
`concluded`	string (ISODate)	Sim	Sempre	Data/hora de conclusão do processamento
`rewardValue`	integer	Não	Se houver recompensa	Valor da recompensa associada
`delivered`	array	Sim	Sempre (pode ser vazio)	Itens de prêmio entregues
`canceled`	array	Sim	Sempre (pode ser vazio)	Itens de prêmio cancelados

Estrutura dos itens em `delivered` e `canceled`

Campo (no item)	Tipo	Obrigatório	Evento	Descrição
`value`	integer	Sim	ambos	Valor do prêmio
`quantity`	integer	Sim	ambos	Quantidade do prêmio
`priceless`	boolean	Sim	ambos	Indica se o prêmio não possui valor
`name`	string	Sim	ambos	Identificador interno do prêmio
`title`	string	Sim	ambos	Descrição do prêmio
`deliveryDetail.timestamp`	ISODate	Sim	ambos	Data/hora do evento de entrega/cancelamento
`deliveryDetail.info`	object	Sim	ambos	Metadados do evento
↳ `coupon`	string	Não	delivered	Código de cupom/voucher (se aplicável)
↳ `paymentId`	string	Sim	ambos	ID interno da recompensa
↳ `description`	string	Sim	delivered	Orientações de resgate
↳ `name`	string	Sim	ambos	Tipo do evento (`delivered`/`canceled`)
↳ `reason`	string	Sim	canceled	Motivo do cancelamento
↳ `reasonCode`	integer	Sim	canceled	Código do motivo
`forwarded`	boolean	Sim	ambos	Indica se o prêmio foi encaminhado

Especificação do callback (padrão Minu)

Método e Content-Type

Padrão: POST com Content-Type: application/json; charset=utf-8
Autenticação com MTLS Content-Type: application/x-www-form-urlencoded
Tokens de autenticação são enviados por meio do header Authorization
Headers customizados não são suportados nas requisições de obtenção de tokens (oauth2)

Autenticação e segurança

TLS 1.2 obrigatório

Outras informações

O header eventParameters é sempre informado pela Aplicação.
customHeaders são opcionais e definidos na subscription. (Apenas na requisição de Notificação do Callback)
O header Authorization só é enviado se o tipo de autenticação exigir.
Para MTLS, o certificado, a chave e a CA (opcional) devem existir no caminho esperado.

Apêndice — Exemplos

Detalhes por tipo de autenticação

a) Bearer

Exemplo de headers:

json

{
  "eventParameters": "{\"eventName\":\"requestProcessed\",\"experience\":\"exp1\",\"accountId\":\"acc123\"}",
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "X-Custom-Header": "valor"
}

b) Basic

Exemplo de headers:

json

{
  "eventParameters": "{\"eventName\":\"requestProcessed\",\"experience\":\"exp1\",\"accountId\":\"acc123\"}",
  "Authorization": "Basic dXNlcjpwYXNzd29yZA==",
  "X-Custom-Header": "valor"
}

c) OAuth2

Como é montado:
1. É feita uma requisição POST para o endpoint de token, enviando:
  - grant_type=client_credentials
  - client_id
  - client_secret
2. O access_token retornado é usado no header:
  - "Authorization": "Bearer <access_token>"

Exemplo de headers:

json

{
  "eventParameters": "{\"eventName\":\"requestProcessed\",\"experience\":\"exp1\",\"accountId\":\"acc123\"}",
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "X-Custom-Header": "valor"
}

d) mTLS

Arquivos necessáriaos:
- Certificado: certificate.crt
- Chave: key.key
- CA (opcional): cacert.crt
Como é montado:
- O agente HTTPS é configurado com o certificado e a chave do cliente.
- Se houver twoFactor.oauth2, segue o fluxo de OAuth2 acima, mas a requisição de token também usa mTLS.
- Se não houver twoFactor, apenas o handshake mTLS é realizado, sem header Authorization.

Exemplo de headers (com twoFactor.oauth2):

json

{
  "eventParameters": "{\"eventName\":\"requestProcessed\",\"experience\":\"exp1\",\"accountId\":\"acc123\"}",
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "X-Custom-Header": "valor"
}

Exemplos de payloads

Request Registered

Caso com erro e reward

json

{
  "id": "req-123",
  "errorCode": "INVALID_DATA",
  "message": "Dados inválidos para registro",
  "rewardValue": 50
}

Caso sem erro, apenas reward

json

{
  "id": "req-124",
  "rewardValue": 100
}

Caso apenas com id

json

{
  "id": "req-125"
}

Request Processed com delivered/canceled

Atual

json

{
  "id": "req-001",
  "data": {
    "orderId": "order-789",
    "customer": "João da Silva",
    "amount": 150.00
  },
  "delivered": [
    { "name": "p1", "value": 100, ... }
  ],
  "canceled": [
    { "name": "p2", "value": 50, ... }
  ],
  "concluded": "2025-08-27T12:00:00Z",
  "rewardValue": 100
}

Legacy

json

{
  "id": "req-001",
  "data": {
    "orderId": "order-789",
    "customer": "João da Silva",
    "amount": 150.00
  },
  "delivered": {
    ...
    "prizes": [
      { "name": "p1", "value": 100, ... }
    ]
  },
  "canceled": {
    ...
    "prizes": [
      { "name": "p2", "value": 50, ... }
    ]
  },
  "concluded": "2025-08-27T12:00:00Z",
  "created": "2025-08-27T12:00:00Z",
  "rewardValue": 100
}

Request Processed sem delivered/canceled

Atual

json

{
  "id": "req-002",
  "data": {
    "orderId": "order-790",
    "customer": "Maria Souza",
    "amount": 200.00
  },
  "delivered": [],
  "canceled": [],
  "concluded": "2025-08-27T13:00:00Z"
}

Legacy

json

{
  "id": "req-002",
  "data": {
    "orderId": "order-790",
    "customer": "Maria Souza",
    "amount": 200.00
  },
  "delivered": {
    "prizes": []
  },
  "canceled": {
    "prizes": []
  },
  "concluded": "2025-08-27T13:00:00Z"
}

Webhooks ​

Como funciona ? ​

Visão geral dos eventos ​

Campos por evento (obrigatórios vs. condicionais) ​

registered-requests ​

processed-requests ​

Estrutura dos itens em delivered e canceled ​

Especificação do callback (padrão Minu) ​

Apêndice — Exemplos ​

Exemplos de payloads ​

Webhooks

Como funciona ?

Visão geral dos eventos

Campos por evento (obrigatórios vs. condicionais)

`registered-requests`

`processed-requests`

Estrutura dos itens em `delivered` e `canceled`

Especificação do callback (padrão Minu)

Apêndice — Exemplos

Exemplos de payloads