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 {"id": "uuid-do-webhook"}. 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 é o UUID retornado no cadastro.

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 200 em menos de 30 segundos.
3. Ser acessível publicamente via HTTPS.
4. Se basic_authentication foi configurado, validar o header Authorization: Basic <base64(usuário:senha)>.