Guia: Webhooks

Fluxo para configurar notificações em tempo real de eventos da plataforma Merx.

Como funciona

Cada webhook registra um evento por vez — webhook_event é um String único (não um array). Para escutar múltiplos eventos, registre um webhook para cada.

1. Registrar webhook

Endpoint: POST /api/v1/integration/webhooks

curl -X POST \
  https://api.merx.tech/api/v1/integration/webhooks \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_event": "CREATE_FARM",
    "url": "https://api.cliente.com/api/v1/receive",
    "basic_authentication": "usuário:senha"
  }'

Campo	Descrição	Obrigatório
webhook_event	Evento que dispara o gatilho (ver tabela abaixo)	Sim
url	URL do endpoint do parceiro (deve aceitar POST)	Sim
basic_authentication	Credenciais usuário:senha enviadas via header Basic Auth	Não

Response: 201 Created com corpo vazio.

Atenção: o cadastro não devolve o id do webhook. A resposta traz um header Location: /api/v1/address/{id} que não deve ser seguido — esse caminho não existe na API. Para obter o id do webhook recém-criado, use GET /api/v1/integration/webhooks (ou GET /api/v1/integration/webhooks/-/events/{webhook_event} para um evento específico).

Detalhes em Cadastrar Webhook.

2. Listar webhooks

Endpoint: GET /api/v1/integration/webhooks

curl -X GET \
  https://api.merx.tech/api/v1/integration/webhooks \
  -H "Authorization: {SUA_API_KEY}"

Detalhes em Buscar Webhooks.

3. Buscar webhook por evento

Endpoint: GET /api/v1/integration/webhooks/-/events/{webhook_event}

O evento vai no path, não como query string.

curl -X GET \
  https://api.merx.tech/api/v1/integration/webhooks/-/events/CREATE_FARM \
  -H "Authorization: {SUA_API_KEY}"

Detalhes em Buscar Webhook por Evento.

4. Atualizar webhook

Endpoint: PUT /api/v1/integration/webhooks

A atualização é feita pelo webhook_event informado no body (não pelo ID no path).

curl -X PUT \
  https://api.merx.tech/api/v1/integration/webhooks \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_event": "CREATE_FARM",
    "url": "https://api.cliente.com/api/v1/receive-v2",
    "basic_authentication": "usuário:senha"
  }'

Detalhes em Atualizar Webhook.

5. Remover webhook

Endpoint: DELETE /api/v1/integration/webhooks/{id}

O id não é devolvido pelo cadastro: obtenha-o em GET /api/v1/integration/webhooks (ou em GET /api/v1/integration/webhooks/-/events/{webhook_event}) antes de remover.

curl -X DELETE \
  https://api.merx.tech/api/v1/integration/webhooks/{webhook_id} \
  -H "Authorization: {SUA_API_KEY}"

Response: 204 No Content. Detalhes em Remover Webhook.

Eventos disponíveis

Evento	Quando dispara
CREATE_PRODUCER / UPDATE_PRODUCER / DELETE_PRODUCER	Ciclo de vida da Companhia Produtora
CREATE_WAREHOUSE / UPDATE_WAREHOUSE / DELETE_WAREHOUSE	Ciclo de vida de Armazém
CREATE_FARM / UPDATE_FARM / DELETE_FARM	Ciclo de vida de Fazenda
CREATE_GUEST_USER / UPDATE_GUEST_USER / DELETE_GUEST_USER	Ciclo de vida de Participante
CREATE_DELIVERY_PLACE / UPDATE_DELIVERY_PLACE / DELETE_DELIVERY_PLACE	Ciclo de vida de Local de Entrega
CREATE_ORDER_COMMITMENT / UPDATE_ORDER_COMMITMENT / DELETE_ORDER_COMMITMENT	Ciclo de vida de Negociação
CREATE_WALLET / UPDATE_WALLET / DELETE_WALLET	Ciclo de vida de Carteira
UPDATE_WORKFLOW_ORDER_COMMITMENT	Mudança de status no workflow da negociação
CHANGE_PRODUCER_STATUS_ESG	Mudança no status ESG do produtor
CHANGE_FARM_STATUS_ESG	Mudança no status ESG da fazenda
PRODUCER_PRODUCTION	Atualização na produção do produtor

Payloads específicos em Eventos de Webhooks.

Requisitos do endpoint receptor

Seu endpoint deve:

1. Aceitar requisições POST com body JSON.
2. Responder com HTTP 2xx em menos de 5 segundos — esse é o timeout de conexão e de leitura usado pela Merx.
3. Ser acessível publicamente via HTTPS.
4. Se basic_authentication foi configurado, validar o header Authorization: Basic <base64(usuário:senha)>.

Toda entrega chega com os headers app-hash (identificador da cooperativa) e event-type (tipo do evento entregue — a única forma de distinguir eventos numa mesma URL), além de Content-Type: application/json.

Chega também o header Content-Hmac. Ele é calculado sobre a mensagem interna que originou a notificação, e não sobre o corpo que você recebe — os dois diferem, porque o corpo é reserializado antes de sair. Não use esse header para validar a entrega, e trate o hmac_secret cadastrado no owner detail como sem efeito prático hoje. Use a autenticação básica do webhook para autenticar a origem.

Sobre a reentrega: responder 5xx devolve a mensagem à fila e ela é reentregue; responder 4xx encerra a entrega em definitivo, com o erro apenas registrado em log. Como o 5xx provoca reentrega, trate o processamento de forma idempotente — o mesmo evento pode chegar mais de uma vez.