Cadastro de Webhooks

Esta seção detalha o processo para o integrador se cadastrar para receber eventos específicos da loja via webhook (notificação em tempo real).

Passo 1: Consultar IDs de Eventos Disponíveis

O integrador deve primeiro consultar a lista completa de eventos que podem ser recebidos via webhook e obter o webhook_event_id correspondente ao evento de interesse.

GET

/auxiliary/webhook-events

Descrição: Retorna a lista de todos os eventos de webhook disponíveis para cadastro.

Passo 2: Cadastrar o Webhook na Loja

Após obter o webhook_event_id, o integrador deve realizar o cadastro da URL de callback e da chave secreta.

POST

/store/{store_id}/webhooks

Payload Cadastrar o Webhook na Loja

{
  "webhooks": [
    {
      "url": "https://seu-servidor.com/webhook/aiqfome",
      "secret_key": "sua_chave_secreta_aqui",
      "webhook_event_id": 12
    }
  ]
}

Detalhamento do Payload

Campo	Tipo	Obrigatório	Descrição
url	STRING	✅	É a URL de callback (ou endpoint) do integrador que irá receber o payload do evento (webhook).
secret_key	STRING	✅	Chave secreta informada pelo próprio integrador no momento do cadastro. Esta chave deve ser usada pelo integrador para validar a autenticidade e acessar os dados do evento ao recebê-lo.
webhook_event_id	INTEGER	✅	O ID do evento (obtido no Passo 1) para o qual o integrador deseja receber notificações.

Formato de Envio de Webhook

O formato de envio utiliza o protocolo HTTP/HTTPS. O integrador deve utilizar a chave secreta cadastrada para autenticar e validar a origem da notificação.

Payload new-order

{
  "event": "new-order",
  "store_id": 13250,
  "data": {
    "order_id": 68650881,
    "created_at": "2025-01-16 17:27:04",
    "user_name": "QA05",
    "is_aiqentrega_delivery": false,
    "order_delivery_time": "40 - 60",
    "order_is_pickup": false,
    "store_id": 13250,
    "store_name": "Habanero Comida Mexicana"
  }
}

Payload read-order

{
  "event": "read-order",
  "store_id": 123,
  "data": {
    "order_id": 12345,
    "read_at": "2024-01-15 14:35:00"
  }
}

Payload ready-order

{
  "event": "ready-order",
  "store_id": 123,
  "data": {
    "order_id": 12345,
    "ready_at": "2024-01-15 15:20:00"
  }
}

Payload cancel-order

{
  "event": "cancel-order",
  "store_id": 123,
  "data": {
    "order_id": 12345,
    "canceled_at": "2024-01-15 15:00:00",
    "reason": "Cliente solicitou cancelamento"
  }
}

Payload order-refund

{
  "event": "order-refund",
  "store_id": 123,
  "data": {
    "order_id": 12345,
    "subtotal": 89.9,
    "refunded_value": 50
  }
}

Payload new-store

{
  "event": "new-store",
  "data": {
    "data": {
      "errors": [],
      "success": [
        {
          "storeId": 123
        }
      ]
    }
  }
}

Payload new-menu

{
  "event": "new-menu",
  "store_id": 123,
  "data": {
    "type": "success",
    "store_id": 123,
    "message": "Menu importado com sucesso para a loja: 123"
  }
}

Payload order-logistic

{
  "event": "order-logistic",
  "store_id": 96236,
  "data": {
    "order_id": 68670449,
    "status": "pickup_ongoing",
    "metadata": {
      "driver_name": "John Doe",
      "driver_phone": "1234567890"
    }
  }
}

1. Headers da Requisição

Os headers contêm a chave secreta cadastrada para a autenticação.

Header	Valor	Descrição
User-Agent	aiqfome	Identifica a origem da requisição.
Content-Type	application/json	Define o formato do corpo (Body) da requisição.
Authorization	<secret_key_cadastrado_pelo_integrador>	A chave secreta (secret_key) que você informou no momento do cadastro do webhook. Você deve usar esta chave para validar a autenticidade da notificação.

2. Corpo da Requisição (Body)

O corpo da requisição é um objeto JSON que informa o tipo de evento (event), a loja (store_id) e os dados detalhados (data).

2.1 Eventos de Ciclo de Pedido

Evento	Descrição
new-order	Disparado quando um novo pedido é criado.
cancel-order	Disparado quando um pedido é cancelado.
read-order	Disparado quando a loja marca o pedido como lido.
ready-order	Disparado quando o pedido é marcado como pronto para entrega/retirada.
order-refund	Disparado quando ocorre um estorno total ou parcial de um pedido.

Obs: Para consultar os eventos e ID's dos eventos utilize o endpoint conforme a documentação na API

Detalhamento do Body (Eventos de Pedido - Campos Chave)

Campo	Evento new-order	Evento cancel-order	Evento read-order	Evento ready-order	Evento order-refund
event	"new-order"	"cancel-order"	"read-order"	"ready-order"	"order-refund"
store_id	ID da loja.	ID da loja.	ID da loja.	ID da loja.	ID da loja.
data.order_id	ID único do pedido.	ID único do pedido.	ID único do pedido.	ID único do pedido.	ID único do pedido.
data.created_at	Data e hora da criação.	—	—	—	—
data.user_name	Nome do cliente.	—	—	—	—
data.is_aiqentrega_delivery	Indica se a entrega é pelo Aiqentrega.	—	—	—	—
data.order_delivery_time	Tempo estimado de entrega.	—	—	—	—
data.order_is_pickup	Indica se é pedido para retirada.	—	—	—	—
data.store_name	Nome da loja.	—	—	—	—
data.canceled_at	—	Data e hora do cancelamento.	—	—	—
data.reason	—	Motivo do cancelamento.	—	—	—
data.read_at	—	—	Data e hora da leitura.	—	—
data.ready_at	—	—	—	Data e hora em que ficou pronto.	—
data.refunded_value	—	—	—	—	Valor total estornado.
data.subtotal	—	—	—	—	Subtotal original do pedido.

2.2 Eventos de Configuração (Loja e Menu)

Evento	Descrição
new-store	Disparado após a criação ou atualização de uma nova loja.
new-menu	Disparado após a importação ou atualização bem-sucedida do menu da loja.

Detalhamento do Body (Eventos de Configuração)

Campo	Evento new-store	Evento new-menu
event	"new-store"	"new-menu"
store_id	—	ID da loja.
data.data.success[]	Array de lojas criadas/atualizadas com sucesso (dentro da estrutura aninhada data.data).	—
data.data.success[].storeId	ID da loja que foi criada/atualizada.	—
data.type	—	Status da operação (Ex: "success").
data.message	—	Mensagem descritiva do resultado da importação.

2.3 Eventos de Logística de Entrega

Para que o parceiro integrador ou canal de vendas receba as atualizações de rastreio, é necessário registrar o evento de logística na loja correspondente.

Evento	Descrição
order-logistic	Notifica todas as mudanças de status do ciclo de entrega (Logística).

Detalhamento do Body do Evento order-logistic

O evento order-logistic utiliza um payload onde o campo status define a etapa atual da entrega. O objeto metadata é utilizado para trafegar informações adicionais do transportador.

Campo	Descrição
event	Nome do evento disparado (order-logistic).
store_id	ID único da loja vinculada ao evento.
data.order_id	ID único do pedido.
data.status	Status logístico atual. Exemplo: pickup_ongoing, delivery_ongoing
data.metadata	Contém informações do motorista (como driver_name e driver_phone) exclusivamente quando o status for pickup_ongoing. Para todos os demais status, este campo retorna vazio.

Atualizar Webhook

Este endpoint permite modificar as configurações de um Webhook cadastrado.

PUT

/store/{store_id}/webhooks/{id}

PATCH

/store/{store_id}/webhooks/{id}

Payload Atualizar Webhook

{
  "url": "https://urlcallback.com.br",
  "webhook_event_id": 1,
  "secret_key": "secret_updated"
}

Parâmetros da URL

Parâmetro	Obrigatório	Descrição
store_id	✅	ID da loja onde o webhook está configurado.
id	✅	ID único do webhook que será atualizado.

Parâmetros do Corpo (Payload)

Campo	Obrigatório	Descrição
url	❌	Nova URL que receberá as notificações.
webhook_event_id	❌	ID do evento que o webhook deve escutar (ex: 1 para pedidos).
secret_key	❌	Nova chave de segurança para validação do payload.

Deletar Webhook

Este endpoint remove permanentemente um Webhook cadastrado em uma loja específica. Uma vez deletado, o sistema interromperá o envio de notificações para aquele evento imediatamente.

DELETE

/store/{store_id}/webhooks/{id}

Parâmetros da URL

Parâmetro	Obrigatório	Descrição
store_id	✅	ID da loja proprietária do webhook.
id	✅	ID único do webhook (evento) que será removido.