Webhooks do painel

Os webhooks do painel são as notificações que a própria loja cadastra na tela API, aba Webhooks. A cada evento escolhido — pedido pago, Pix gerado, cliente criado e outros — a Appmax envia um POST com os dados do evento para a URL da loja.

Não confunda com os webhooks da Appstore

Quem desenvolve um aplicativo recebe os webhooks da Appstore, com outro envelope (app_id, site_id, external_key) e outra lista de eventos. Esta página é só para quem integra a própria loja.

Usando um assistente de IA

O contexto do Guia para IA (tela API) já avisa o assistente que a loja recebe estes webhooks e aponta para esta página. Cole o contexto no início da conversa: o MCP da documentação ainda não indexa esta página e, sozinho, leva o assistente aos webhooks da Appstore.

Como a entrega chega

Cada evento gera um POST com corpo JSON e três campos de primeiro nível:

{
  "environment": "production",
  "event": "OrderPaid",
  "data": { "id": 99042, "status": "aprovado", "...": "..." }
}

Campo	Descrição
environment	Ambiente que gerou o evento. Sandbox e Produção enviam production; não use este campo para separar os ambientes — use URLs diferentes em cada um.
event	Nome do evento. É o identificador da tabela abaixo com a primeira letra maiúscula (orderPaid → OrderPaid).
data	Dados do recurso: pedido, cliente ou assinatura, conforme o evento.

A requisição chega com o header User-Agent: apphook.

Eventos

São os mesmos 28 eventos da aba Webhooks, agrupados como lá.

Pedidos

Evento (event)	Quando dispara	data
OrderApproved	Pedido aprovado	pedido
OrderAuthorized	Pedido autorizado	pedido
OrderAuthorizedWithDelay	Pedido autorizado, enviado 60 minutos depois	pedido
OrderIntegrated	Pedido integrado	pedido
OrderPendingIntegration	Pedido pendente de integração	pedido
OrderPaid	Pedido pago	pedido
OrderRefund	Pedido estornado	pedido
OrderPartialRefund	Pedido estornado parcialmente	pedido
OrderUpSold	Upsell pago	pedido
OrderRefusedByRisk	Pedido recusado pelo antifraude	pedido

Pagamentos

Evento (event)	Quando dispara	data
OrderPixCreated	Pix gerado	pedido
OrderPaidByPix	Pix pago	pedido
OrderPixExpired	Pix expirado	pedido
OrderBilletCreated	Boleto gerado	pedido
OrderBilletOverdue	Boleto vencido	pedido
PaymentNotAuthorized	Pagamento não autorizado	pedido, com issuer_message
PaymentNotAuthorizedWithDelay	Pagamento não autorizado, enviado 60 minutos depois	pedido, com issuer_message
OrderChargeBackInTreatment	Chargeback em tratamento	pedido
OrderChargeBackGain	Chargeback ganho	pedido

Clientes

Evento (event)	Quando dispara	data
CustomerCreated	Cliente criado	cliente
CustomerContacted	Cliente contatado	cliente
CustomerInterested	Cliente interessado, enviado 60 minutos depois	cliente

Assinaturas

Evento (event)	Quando dispara	data
SubscriptionDelayedEvent	Assinatura atrasada	cliente, com subscription
SubscriptionCancellationEvent	Assinatura cancelada	cliente, com subscription
CreatedSubscription	Assinatura criada	ciclo de vida da assinatura
CanceledSubscription	Assinatura cancelada	ciclo de vida da assinatura
ChargeSuccess	Cobrança da assinatura aprovada	ciclo de vida da assinatura
ChargeFailed	Falha na cobrança da assinatura	ciclo de vida da assinatura

O que vem em data

Pedido

Grupo	Campos
Identificação	id, customer_id, status, origin, created_at, paid_at, refunded_at, integrated_at, upsell_order_id, invoice_id, payment_link_id
Valores	total_products, freight_value, freight_type, discount, interest, total, full_payment_amount, total_refunded, refund_amount, cashback, partner_total, partner_affiliate_total
Pagamento	payment_type, installments, card_brand, card_details, issuer_message
Pix	pix_creation_date, pix_expiration_date, pix_emv, pix_ref, pix_qrcode, pix_end_to_end_id, pix_payment_link
Boleto	billet_url, billet_digitable_line, billet_date_overdue, order_billet_payment_code
Relacionados	customer, bundles, products, visit, traffic_description
Empresa e comissões	company_name, company_cnpj, company_email, co_production_commission, affiliate_comission, seller_name

Campos que não se aplicam ao pedido chegam como null — os de Pix num pedido de cartão, por exemplo. issuer_message só é preenchido nos eventos de pagamento não autorizado.

Exemplo de data de pedido (resumido, dados fictícios)

{
  "id": 99042,
  "customer_id": 17,
  "status": "aprovado",
  "payment_type": "CreditCard",
  "card_brand": "Visa",
  "installments": 12,
  "total_products": 242.03,
  "freight_value": 39.99,
  "freight_type": "PAC",
  "discount": 0,
  "interest": 57.97,
  "total": 339.99,
  "paid_at": "2026-10-01 15:02:52",
  "created_at": "2026-10-01 15:02:36",
  "origin": "API",
  "customer": {
    "id": 17,
    "firstname": "Maria",
    "lastname": "Silva",
    "email": "[email protected]",
    "document_number": "00000000000"
  },
  "bundles": [
    {
      "id": 23,
      "name": "Livro de receitas",
      "products": [{ "sku": "9000010", "name": "Livro de receitas", "price": "121.02", "quantity": 2 }]
    }
  ],
  "company_name": "Minha Loja",
  "issuer_message": null
}

Cliente

id, firstname, lastname, fullname, email, telephone, document_number, hash, endereço (postcode, address_street, address_street_number, address_street_complement, address_street_district, address_city, address_state, uf), site_id, created_at, interested_bundle (o produto de interesse, com link para o checkout) e visited_url.

Assinatura

• SubscriptionDelayedEvent e SubscriptionCancellationEvent: os campos de cliente mais um objeto subscription com id, installments, total, created_at, cancelled_at e o bundle assinado (com os produtos).
• CreatedSubscription, CanceledSubscription, ChargeSuccess e ChargeFailed: o ciclo de vida da assinatura, com order_id e subscription_id. Conforme o evento, vêm também interval e interval_count (na criação), uuid (nas cobranças) e status.

Atrasos, novas tentativas e tempo de resposta

• Envio imediato, exceto nos três eventos marcados com 60 minutos na tabela, que só saem uma hora depois do fato.
• Responda com HTTP 2xx. Qualquer outro status, ou falha de conexão, conta como erro.
• Até 4 tentativas no total. Depois de um erro, a Appmax espera 10 segundos, depois 100 e depois 1.000 (cerca de 17 minutos) antes de cada nova tentativa. Esgotadas as tentativas, a entrega é descartada.
• Responda rápido. Coloque o evento numa fila e devolva 200 antes de processar — uma resposta lenta pode estourar o tempo limite e virar uma nova tentativa.

Segurança

As entregas não são assinadas: não há header de assinatura para validar. Para não aceitar chamadas forjadas:

• Use uma URL HTTPS com um caminho difícil de adivinhar (por exemplo, com um token aleatório) e não a publique.
• Antes de agir sobre um evento sensível — liberar um pedido pago, por exemplo —, confirme pela API: consulte o pedido com GET /v1/orders/{order_id} usando o data.id recebido.
• Ignore eventos repetidos: guarde o event com o data.id já processados.

Testar o endpoint

Na lista de webhooks da aba Webhooks, o botão Testar envia para a URL o primeiro evento que o webhook assina, com dados fictícios. Use para validar que o endpoint responde 2xx — não para conferir valores de um pedido real.

Histórico de entregas, reenvio e regras condicionais ficam na tela completa de webhooks do painel.