Webhooks

Criar Webhook

Cadastra um endereço para receber eventos

POST

/v1/webhooks

Escopo

webhooks.gerenciar

O segredo de assinatura só aparece nesta resposta. Guarde-o para conferir o cabeçalho X-HDL-Assinatura.
Até 10 webhooks por loja.

Autorização

Authorizationstringobrigatórioheader

Chave da API no formato Bearer hdl_live_.... Crie no painel da loja em Integração › API e webhooks. Saiba mais.

Corpo da requisição

urlstringobrigatóriobody · application/json

https público (porta 443), sem IP interno.

eventosstring[]obrigatóriobody · application/json

pedido.criado, pedido.status_alterado, pedido.pago, pedido.cancelado.

Resposta

201 — objeto { "dados": {...} } com um Webhook.

Erros possíveis

HTTP	código	quando
`401`	`nao_autenticado`	Faltou o cabeçalho Authorization: Bearer <chave>.
`401`	`chave_invalida`	Chave inexistente ou revogada.
`403`	`sem_permissao`	A chave não tem o escopo exigido pelo endpoint.
`409`	`mesmo_status`	O pedido já está no status pedido.
`409`	`pedido_encerrado`	Pedido cancelado ou reembolsado não muda mais.
`409`	`estoque_insuficiente`	Saída maior que o saldo.
`409`	`limite_do_plano`	A loja atingiu o limite de produtos do plano.
`409`	`limite_webhooks`	A loja já tem 10 webhooks.
`409`	`conflito`	O recurso mudou durante a chamada: consulte e tente de novo.
`422`	`validacao`	Campos inválidos: veja o objeto "campos".

curl --request POST \ --url 'https://api.hoteldaslojas.com.br/v1/webhooks' \ --header 'Authorization: Bearer <chave>' \ --header 'Content-Type: application/json' \ --data '{"url": "https://erp.exemplo.com.br/webhooks/hotel", "eventos": ["pedido.criado", "pedido.status_alterado"]}'

import os, requests resposta = requests.post( "https://api.hoteldaslojas.com.br/v1/webhooks", headers={"Authorization": f"Bearer {os.environ['HDL_CHAVE']}"}, json={ "url": "https://erp.exemplo.com.br/webhooks/hotel", "eventos": [ "pedido.criado", "pedido.status_alterado" ] }, timeout=30, ) resposta.raise_for_status() print(resposta.json()["dados"])

<?php $ch = curl_init('https://api.hoteldaslojas.com.br/v1/webhooks'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('HDL_CHAVE'), 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'url' => 'https://erp.exemplo.com.br/webhooks/hotel', 'eventos' => ['pedido.criado', 'pedido.status_alterado'] ]), ]); $resposta = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); print_r($resposta);

{ "dados": { "id": 1, "url": "https://erp.exemplo.com.br/webhooks/hotel", "eventos": [ "pedido.criado", "pedido.status_alterado" ], "ativo": true, "falhas_seguidas": 0, "ultimo_envio": null, "ultimo_status_http": null, "criado_em": "2026-10-28T00:43:12-03:00", "segredo": "9f2c6a1e5b7d4c3a8e0f1b2d3c4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6a" } }

{ "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } }