Global Construção - Configurações - Webhooks

• Ocorre quando um contrato é inserido com sucesso.

Especificação da requisição

Objeto

• Método: Post
• Body: raw/json

[{"cto_in_codigo":"190", //código do contrato recém gerado
"cnd_in_codigo":"12001", //código da proposta do mega
"cnd_in_propostaexterna":"3392" //código da proposta do sistema externo de pré-venda
},
{
"cto_in_codigo":"191", //código do contrato recém gerado
"cnd_in_codigo":"12002", //código da proposta do mega
"cnd_in_propostaexterna":"3393" //código da proposta do sistema externo de pré-venda
}]

"x_tenant": "888a0263-6526-4152-851d-e916k3504b70" //identificador do cliente na mega, quando cloud
"cliente": "60630221000175" //identificador do cliente (cnpj sem caracteres especiais)
"hmac_secret": " /* Método + Body + Url criptografados com este método*/"

• Ocorre quando um novo contrato é registrado no ERP.

{
   "id": "550e8400-e29b-41d4-a716-446655440001",
   "type": "carteirarecebiveis.contrato.criado",
   "created_at": "2026-08-01T08:50:53.751-03:00",
   "api_version": "v1",
   "data": [
     {
        "cto_in_codigo": "12345",
        "cnd_in_codigo": "678",
        "cnd_in_propostaexterna": "90"
     }
  ]
}

• Ocorre quando há alteração nos dados do contrato ou de suas parcelas, taxas, garantias, clientes envolvidos, entre outros.
• As alterações realizadas no ERP, por integração ou diretamente no banco de dados podem gerar este evento.
• Os eventos são processados em ciclos de 1 minuto. Alterações realizadas no mesmo contrato durante esse período geram apenas um registro no payload.
• Quando mais de um contrato é alterado no mesmo ciclo, todos são enviados em uma única requisição.

{
   "id": "550e8400-e29b-41d4-a716-446655440000",
   "type": "carteirarecebiveis.contrato.atualizado",
   "created_at": "2026-08-01T08:50:53.751-03:00","api_version": "v1",
   "data": [
     { "cto_in_codigo": "12345", "cnd_in_codigo": "678", "cnd_in_propostaexterna": "90" },
     { "cto_in_codigo": "12346", "cnd_in_codigo": "679", "cnd_in_propostaexterna": "" }
  ]
}

• Ocorre quando um contrato é removido do ERP.

{
   "id": "550e8400-e29b-41d4-a716-446655440002",
   "type": "carteirarecebiveis.contrato.excluido",
   "created_at": "2026-08-01T08:50:53.751-03:00",
   "api_version": "v1",
   "data": [
     {
        "cto_in_codigo": "12345",
        "cnd_in_codigo": "678",
        "cnd_in_propostaexterna": "90"
     }
  ]
}

Todos os eventos usam o mesmo envelope JSON:

{
"id": "550e8400-e29b-41d4-a716-446655440001",
"type": "carteirarecebiveis.contrato.criado",
"created_at": "2026-08-01T08:50:53.751-03:00",
"api_version": "v1",  
"data": [  
    {  
        "cto_in_codigo": "12345",  
        "cnd_in_codigo": "678",  
        "cnd_in_propostaexterna": "90"  
        }  
        ]  
        }

Campos do envelope

Campos de objeto em data

Após processar o evento, seu endpoint deve responder com um código de status HTTP da faixa 2xx (200, 201, 202 ou 204).

POST https://api.suaempresa.com/webhooks/mega HTTP/1.1
Content-Type: application/json; charset=utf-8
x_tenant: 12345678000195_PROD
x_cliente: 12345678000195
hmac_secret: a3f5c9d2e1b8f047c6a2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4

{
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "carteirarecebiveis.contrato.criado",
    "created_at": "2026-08-01T00:50:53.751-03:00",
    "api_version": "v1",
    "data": [
        {
            "cto_in_codigo": "12345",
            "cnd_in_codigo": "678",
            "cnd_in_propostaexterna": "90"
            }
            ]
            }

O ERP Senior Mega utiliza um mecanismo de retentativas com intervalo crescente (exponential backoff) para garantir a entrega dos eventos.

O campo id de cada evento é um UUID único e imutável. Em cenários de retentativa.

Recomendamos que seu sistema armazene os id processados e ignore eventos com id já visto. Isso torna sua integração segura a duplicatas.

Ao receber um evento, siga os passos abaixo:

1. Verifique se o id já foi processado;
2. Se sim: responda 200 e ignore;
3. Se não: processe e marque o id como processado.

O campo api_version informa a versão do contrato de eventos. Atualmente "v1".

Mudanças que quebram compatibilidade serão sempre acompanhadas de incremento de versão e comunicação prévia. Mudanças aditivas (novos campos opcionais) podem ocorrer sem incremento de versão. Recomendamos que seu parser ignore campos desconhecidos.

Valide seu endpoint antes de ser cadastrado

Ferramentas como webhook.site ou RequestBin permitem criar um endpoint temporário para inspecionar as requisições antes de implementar seu handler.

Checklist de validação

• Meu endpoint está acessível via HTTPS
• Respondo HTTP 2xx em menos de 10 segundos
• Valido a assinatura HMAC-SHA256 antes de processar
• Implemento idempotência pelo campo id
• Meu parser ignora campos extras desconhecidos no JSON
• Processo os três tipos de evento (criado, atualizado, excluido)
• Trato o campo data como array (pode conter múltiplos contratos)