Guia do usuário: webhooks

Guia do usuário: webhooks

🔐 Introdução ao uso de Webhooks

Nossa plataforma permite que você configure webhooks para receber atualizações automáticas sobre eventos importantes relacionados aos seus pedidos e incidentes. Isso permite que você mantenha seus sistemas sincronizados sem a necessidade de consultas manuais.

📌 O que são Webhooks?

Um webhook é uma chamada automática que nosso sistema faz para uma URL configurada por você sempre que um evento relevante ocorre (como uma alteração no status de um pedido ou incidente). Dessa forma, seu sistema pode reagir imediatamente a essas alterações.

🔑 Configuração inicial

Para começar a usar webhooks:
  1. Acesse a seção Minha conta > Token de acesso .
  2. Crie uma chave de API com permissões sobre seus pedidos e problemas.
  3. Configurar dois endpoints (URLs públicos):
  4. Um para receber atualizações de status do pedido .
  5. Outro para receber atualizações de status de incidentes .

✅ Segurança: assinaturas HMAC (opcional por enquanto)

Para validar a autenticidade dos eventos que você recebe, cada webhook pode incluir uma assinatura digital no cabeçalho:
  1. Cabeçalho : X-Dropea-Hmac-Sha256
  2. Conteúdo : Um hash SHA256 gerado usando o corpo POST (payload) e sua chave de API correspondente como a chave secreta.
Isso permite que você verifique se a solicitação está realmente vindo do nosso sistema e não foi alterada, semelhante ao que o Shopify faz com seu sistema de webhooks .

⚠️ Importante: A validação de assinatura é atualmente opcional, mas sua implementação é recomendada para reforçar a segurança.

🛍️ Atualização do status do pedido

Quando o status de um pedido é atualizado, o sistema envia uma notificação ao webhook configurado com a seguinte estrutura de evento:

❌ Exemplo 1: O pedido passa de Confirmado para Cancelado (Carga útil para Recebimento)
  1. {"tópico":"atualização_de_status_do_pedido","id_do_pedido":265494,"status_anterior":"confirmado","novo_status":"cancelado","atualizado_em":"29/05/2025 14:14:58"}

✅ Exemplo 2: O pedido passa de Pendente para Confirmado (Carga Útil para Recebido)
  1. {"tópico":"atualização_de_status_do_pedido","id_do_pedido":265494,"status_anterior":"pendente","novo_status":"confirmado","atualizado_em":"29/05/2025 14:14:58"}

🔁 Exemplo 3: O pedido vai de Erro para Pendente (Carga útil para Recebimento)
  1. {"tópico":"pedido:atualização_de_status",
  2. "order_id":265496,"prev_status":"error","new_status":"pending","updated_at":"2025-05-29 14:38:05"}

🛠️ Atualização de incidência

📌 Exemplo: Incidente passa de Pendente para Tratado pelo Cliente (Carga Útil para Recebido)
  1. {
  2. "tópico": "incidência:atualização_de_status",
  3. "new_status": "gerenciado pelo cliente",
  4. "updated_at": "2025-02-13 14:23:56",
  5. "prev_status": "pendente",
  6. "incidence_id": 189044
  7. }

🔄 Exemplo 2: Incidente passa de Pendente para Solução Enviada
  1. {
  2. "tópico": "incidência:atualização_de_status",
  3. "incidence_id": 265494,
  4. "prev_status": "cliente_gerenciado",
  5. "new_status": "resolução_enviada",
  6. "atualizado em": "2025-05-29 16:10:45"
  7. }

✅ Exemplo 3: O incidente passa de Solução Enviada para Resolvido (Carga Útil para Recebido)
  1. {
  2. "tópico": "incidência:atualização_de_status",
  3. "incidence_id": 265494,
  4. "prev_status": "envio_de_solução",
  5. "new_status": "resolvido",
  6. "atualizado em": "2025-05-29 17:42:30"
  7. }

📌 Detalhes por campo


Campo
Cara Descrição
tópico
corda
Pode ser "order:status_update" ou "incidence:status_update" , dependendo da origem do evento.
id_do_pedido
inteiro
ID do pedido afetado. Presente somente se o tópico for order:status_update.
id_de_incidência
inteiro
ID do problema afetado. Presente somente se o tópico for incidence:status_update.
status_anterior
corda
Estado anterior do objeto. Por exemplo, "pendente", "confirmado", "erro".
novo_status
corda
Novo estado após mudança.
atualizado_em
data
Data e hora da alteração. Este campo está no fuso horário Europa/Madri , que é:
— UTC+2 no verão (horário de verão)
— UTC+1 no inverno (horário padrão)