Webhooks

1. Introdução

1.1 Nome do Serviço

O serviço, denominado business-webhook, tem como propósito principal notificar os clientes sobre eventos específicos relacionados à plataforma. Utilizando webhooks, podemos enviar notificações através de chamadas POST para URLs fornecidas pelos clientes.

1.2 Eventos Suportados

Atualmente, o webhook suporta dois eventos principais:

registered-requests: Acionado quando um pedido é registrado na plataforma.
- Este evento é notificado em casos de sucesso e erro.
processed-requests: Disparado quando um pedido é processado.
- Este evento é notificado apenas em casos de sucesso no processamento do pedido.

1.3 Exemplos de Uso

Assim que o pedido entra na plataforma, é gerado o evento registered-requests. O cliente passa a receber a notificação incluindo id do pedido na Minu e, se aplicável, rewardValue. Nos casos onde ocorre erro, errorCode e message podem ser fornecidos.
Após a trajetória do pedido no sistema, finalizando com seu processamento, o evento processed-requests é acionado. Os dados a serem notificados incluem requestId e informações da request como: deliveredPrizes, canceledPrizes, createdDate, concludedDate e, se aplicável, rewardValue.

1.4 Autenticação Suportada

O business-webhook atualmente oferece suporte a diversos métodos de autenticação, discutidos em detalhes na seção específica.

2. Formas de receber as notificações de pedidos

Os clientes podem configurar URLs de callback com ou sem autenticação para cada evento.

Exemplo de configurações:

Não receber notificações para registered-requests do plano-bronze.
Receber notificações de processed-requests do plano-bronze em uma URL específica.
Receber notificações de ambos os eventos do plano-prata na mesma URL.
Receber notificações em URLs separadas para ambos eventos do plano-ouro.
Ou inclusive receber todas as notificações de todas as experiências na mesma URL.

2.1 Inscrição por pedido

Enviar a URL para notificação diretamente no body da requisição dos pedidos:

json

{
  "experience": "nome-da-campanha",
  "data": {
    // dados do pedido
  },
  "event": "evento-da-campanha",
  "registeredCallbackUrl": "URL da API de destino da notificação quando o pedido for registrado (registered-request) pela Minu",
  "processedCallbackUrl": "URL da API de destino da notificação quando o pedido for processado (processed-request) com sucesso pela Minu"
}

2.2 Inscrição por cliente

Quando as URLs permanecem as mesmas para todos os pedidos, habilite o envio de notificações uma única vez, informando eventos, URLs e dados de autenticação.

2.3 Inscrição por experiência/campanha

Permite definir URLs diferentes para cada campanha. Solicite o ajuste para a Minu informando eventos, URLs, experiências e dados de autenticação.

3. Informações de Contrato

3.1 Evento `registered-requests`

Exemplo:

json

{
  "id": "61df44be9a9c9310d70a9831",
  "rewardValue": "100",
  "errorCode": "9999",
  "message": "teste"
}

Campos obrigatórios:

Propriedade	Tipo	Descrição
id*	string	Identificador do pedido na plataforma Minu.
rewardValue	integer	Valor da recompensa a ser entregue. Retornado apenas quando há recompensa.
errorCode	string	Código de erro interno da plataforma Minu. Retornado apenas em erro.
message	string	Mensagem de erro. Retorna apenas quando há mensagem a ser exibida.

3.2 Evento `processed-requests`

Exemplo:

json

{
  "id": "61df44be9a9c9310d70a9831",
  "rewardValue": 10000000,
  "concluded": "0000-00-00T00:00:00.000Z",
  "delivered": [
    {
      "value": 10000000,
      "quantity": 10000000,
      "name": "nome-da-experiência",
      "title": "Título da Experiência",
      "deliveryDetail": {
        "timestamp": "0000-00-00T00:00:00.000Z",
        "info": {
          "name": "delivered",
          "bucket": "nomeDoPremio",
          "coupon": "f1317XXXXX",
          "paymentId": "65972b0e2cdd96e4c0XXXXXX",
          "requestId": "65972b0e2cdd96e4c0XXXXXX",
          "triggerId": "65972b0e2cdd96e4c0XXXXXX",
          "rewardId": "65972b0e2cdd96e4c0XXXXXX",
          "description": "Descrição da entrega"
        },
        "forwarded": false
      }
    }
  ],
  "canceled": [
    {
      "value": 10000000,
      "quantity": 10000000,
      "priceless": false,
      "name": "nome-da-experiência",
      "title": "Título da Experiência",
      "deliveryDetail": {
        "timestamp": "0000-00-00T00:00:00.000Z",
        "info": {
          "name": "canceled",
          "reason": "Motivo do cancelamento",
          "reasonCode": 5,
          "description": "Descrição do cancelamento.",
          "paymentId": "65983b14c183c71c80e77ed5"
        },
        "forwarded": false
      }
    }
  ]
}

Campos obrigatórios:

Propriedade	Tipo	Descrição
id*	string	Identificador do pedido na plataforma Minu.
rewardValue	integer	Valor da recompensa a ser entregue. Retornado apenas quando há recompensa.
concluded*	string	Data e hora da conclusão do processamento do pedido.
delivered*	array	Array de objetos com informações dos prêmios entregues.
canceled*	array	Array de objetos com informações dos prêmios cancelados.

4. Rotina de Retentativa

O business-webhook possui uma rotina de retentativa para garantir o envio das notificações. Se ocorrer um erro em uma chamada para a URL do cliente, os dados da notificação são armazenados para até 5 tentativas de envio, com intervalos de 3 horas entre cada uma.

5. Tipos de Autenticação Suportados

O business-webhook oferece suporte aos seguintes tipos de autenticação:

Bearer Token: Inclusão de um token de acesso no cabeçalho Authorization.
Basic Token: Codificação do nome de usuário e senha em base64, incluída no cabeçalho Authorization.
OAuth2.0: Framework de autorização para acesso a recursos em nome de um usuário.
mTLS (Mutual TLS): Autenticação mútua usando certificados digitais durante o handshake TLS/SSL.

É possível utilizar mTLS em conjunto com qualquer um dos outros métodos para reforçar a segurança das notificações. Todos os métodos estão disponíveis inclusive nas rotinas de retentativas.

API

Propriedades disponíveis na configuração do Webhooks

Propriedade	Tipo	Descrição
`_id`	`string`	Identificador único da subscription.
`accountId`	`string`	Identificador da conta associada à subscription.
`event`	`string`	Tipo de evento que será notificado via callback.
`description`	`string`	Descrição breve da subscription.
`active`	`boolean`	Indica se a subscription está ativa.
`experiences`	`array`	Lista de experiências consideradas para envio da notificação.
`callback`	`object`	Informações do callback associado à subscription.
↳ `url`	`string`	URL do callback.
↳ `authorization`	`object`	Informações de autorização do callback.
↳ ↳ `Basic`	`string`	Tipo de autorização Basic
↳ ↳ `Bearer`	`string`	Tipo de autorização Bearer
↳ ↳ `oauth2`	`object`	Informações de autenticação OAuth2 do callback.
↳ ↳ ↳ `client_id`	`string`	ID do cliente OAuth2.
↳ ↳ ↳ `client_secret`	`string`	Segredo do cliente OAuth2.
↳ ↳ ↳ `url`	`string`	URL do endpoint OAuth2.
↳ ↳ ↳ `audience`	`string`	Público-alvo do token OAuth2.
↳ ↳ `mtls`	`object`	Informações de autorização mTLS do callback.
↳ ↳ ↳ `twoFactor`	`object`	Informações de autenticação de dois fatores do callback.
↳ ↳ ↳ ↳ `oauth2`	`object`	Informações de autenticação OAuth2 do callback.
↳ ↳ ↳ ↳ ↳ `client_id`	`string`	ID do cliente OAuth2.
↳ ↳ ↳ ↳ ↳ `client_secret`	`string`	Segredo do cliente OAuth2.
↳ ↳ ↳ ↳ ↳ `url`	`string`	URL do endpoint OAuth2.
↳ ↳ ↳ ↳ ↳ `audience`	`string`	Público-alvo do token OAuth2.
↳ `customHeaders`	`object`	Cabeçalhos customizados do callback.

Listar Subscriptions

Método HTTP: GET

URL: /subscriptions

Exemplo de Requisição

http

curl --location --request GET 'https://api.minu.biz/v2/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'

Exemplo de Resposta

Se a requisição for bem sucedida, a API retornará as seguintes propriedades no formato JSON.

json


[
  {
    "_id": "691770a90becaf552c201261",
    "accountId": "56dd875f00d3db01005f872a",
    "event": "registered-request",
    "callback": {
      "url": "https://test/integracao/callback/minu"
    },
    "description": "Evento registered-request para o cliente Homologacao Minutrade",
    "experiences": [
      "empresa-teste-callback"
    ],
    "active": true
  },
  {
    "_id": "691770a90becaf552c201423",
    "callback": {
      "url": "https://test/integracao/callback/minu",
      "authorization": {
        "mtls": {
          "twoFactor": {
            "oauth2": {
              "client_id": "client-id",
              "client_secret": "client-secret",
              "url": "https://my-callback-url.com/oauth/token"
            }
          }
        }
      }
    },
    "accountId": "56dd875f00d3db01005f872a",
    "event": "processed-request",
    "description": "Evento processed-request para o cliente Homologacao Minutrade",
    "experiences": [],
    "active": false
  }
]

Criar Subscriptions

Método HTTP: POST

URL: /subscriptions

Exemplo de Requisição

http

curl --location --request POST 'https://api.minu.biz/v2/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "callback": {
        "url": "https://my-callback-url.com/webhook",
        "authorization": {
            "Basic": "bearer",
            "Bearer": "eyJraWQiOi",
            "oauth2": {
              "client_id": "client-id",
              "client_secret": "client-secret",
              "url": "https://my-callback-url.com/oauth/token"
            }
        }
    },
    "event": "processed-request",
    "description": "Webhook para pedidos processados",
    "experiences": ["exp-9299"]
}'

Exemplo de Resposta

Se a requisição for bem sucedida, a API retornará as seguintes propriedades no formato JSON.

json

{
  "event": "processed-request",
  "experiences": [
    "exp-9299"
  ],
  "accountId": "56dd875f00d3db01005f872a",
  "callback": {
    "url": "https://my-callback-url.com/webhook",
    "authorization": {
      "Basic": "bearer",
      "Bearer": "eyJraWQiOi",
      "oauth2": {
        "client_id": "client-id",
        "client_secret": "client-secret",
        "url": "https://my-callback-url.com/oauth/token"
      }
    }
  },
  "description": "Webhook para pedidos processados",
  "_id": "69b807b62e193031e65bec03"
}

Atualizar Subscriptions

Método HTTP: PUT

URL: /subscriptions/{subscriptionId}

Exemplo de Requisição

http

curl --location --request PUT 'https://api.minu.biz/v2/subscriptions/69b807b62e193031e65bec03' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{bearerToken}}' \
--header 'Cookie: XSRF-TOKEN=4812a8f6-8c69-434a-b76b-1b1a7754e557' \
--data '{
    "callback": {
        "url": "https://alterada.com/webhook",
        "authorization": {
            "Basic": "bearer alterado2"
        }
    },
    "description": "ALTERANDO DESCRIPTION 2",
    "experiences": ["NOVA EXPERIENCE", "NOVA EXPERIENCE 2"]
}'

Exemplo de Resposta

Se a requisição for bem sucedida, a API retornará as seguintes propriedades no formato JSON.

json

{
  "experiences": [
    "NOVA EXPERIENCE",
    "NOVA EXPERIENCE 2"
  ],
  "callback": {
    "url": "https://alterada.com/webhook",
    "authorization": {
      "Basic": "bearer alterado2"
    }
  },
  "description": "ALTERANDO DESCRIPTION 2",
  "_id": "69b807b62e193031e65bec03"
}

Webhooks ​

1. Introdução ​

1.1 Nome do Serviço ​

1.2 Eventos Suportados ​

1.3 Exemplos de Uso ​

1.4 Autenticação Suportada ​

2. Formas de receber as notificações de pedidos ​

2.1 Inscrição por pedido ​

2.2 Inscrição por cliente ​

2.3 Inscrição por experiência/campanha ​

3. Informações de Contrato ​

3.1 Evento registered-requests ​

3.2 Evento processed-requests ​

4. Rotina de Retentativa ​

5. Tipos de Autenticação Suportados ​

API ​

Propriedades disponíveis na configuração do Webhooks ​

Listar Subscriptions ​

Exemplo de Requisição ​

Exemplo de Resposta ​

Criar Subscriptions ​

Exemplo de Requisição ​

Exemplo de Resposta ​

Atualizar Subscriptions ​

Exemplo de Requisição ​

Exemplo de Resposta ​

Webhooks

1. Introdução

1.1 Nome do Serviço

1.2 Eventos Suportados

1.3 Exemplos de Uso

1.4 Autenticação Suportada

2. Formas de receber as notificações de pedidos

2.1 Inscrição por pedido

2.2 Inscrição por cliente

2.3 Inscrição por experiência/campanha

3. Informações de Contrato

3.1 Evento `registered-requests`

3.2 Evento `processed-requests`

4. Rotina de Retentativa

5. Tipos de Autenticação Suportados

API

Propriedades disponíveis na configuração do Webhooks

Listar Subscriptions

Exemplo de Requisição

Exemplo de Resposta

Criar Subscriptions

Exemplo de Requisição

Exemplo de Resposta

Atualizar Subscriptions

Exemplo de Requisição

Exemplo de Resposta