Cadastrar Webhook

Endpoints para criar, listar e remover webhooks de notificacao.

---

Criar Webhook

POST /api/external/webhooks

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	String	Sim	ApiKey {client_id}:{client_secret}
Content-Type	String	Sim	application/json
hmac	String	Sim	Assinatura HMAC-SHA512 do body (saiba mais)

Request Body

Campo	Tipo	Obrigatorio	Padrao	Descricao
url	String	Sim	--	URL para receber notificacoes (HTTPS por padrao)
events	Array	Nao	todos	Lista de eventos para assinar. Se omitido, assina todos.
allow_insecure	Boolean	Nao	false	Permite URLs HTTP (nao-HTTPS). A seguranca dos dados e responsabilidade do cliente.

Eventos disponiveis:

Evento	Descricao
pix.charge.created	QR code gerado
pix.charge.paid	PIX recebido e liquidado
pix.charge.expired	QR code expirado (24h)
pix.payout.processing	PIX enviado, aguardando confirmacao
pix.payout.confirmed	PIX enviado e confirmado
pix.payout.failed	PIX enviado rejeitado
pix.payout.returned	PIX enviado devolvido
pix.refund.requested	MED recebido, fundos bloqueados
pix.refund.completed	MED finalizado
pix.return.received	Devolucao PIX recebida (credito)
webhook.test	Teste manual

Exemplo

BODY='{"url":"https://seusite.com.br/webhook","events":["pix.charge.paid","pix.payout.confirmed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Resposta de Sucesso (201)

{
  "worked": true,
  "id": "wh_a1b2c3d4e5f6",
  "url": "https://seusite.com.br/webhook",
  "events": ["pix.charge.paid", "pix.payout.confirmed"],
  "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "description": null,
  "is_active": true,
  "created_at": "2026-03-07T15:30:00Z"
}

Resposta de Erro (422)

{
  "worked": false,
  "detail": "URL deve utilizar HTTPS"
}

Apenas HTTPS por Padrao

A URL do webhook deve utilizar HTTPS. URLs com HTTP serao rejeitadas, a menos que allow_insecure: true seja enviado no cadastro.

Importante — Secret do Webhook

O campo secret retornado na resposta de cadastro e a chave usada para assinar as entregas do webhook (HMAC-SHA256). Armazene esse valor com seguranca — ele nao sera exibido novamente.

NAO confunda com client_secret:

• client_secret = autenticacao das suas requisicoes a API (header Authorization)
• secret do webhook = verificacao da assinatura das entregas recebidas (header X-Owem-Signature)

Se voce nao enviar o campo secret no cadastro, um valor aleatorio sera gerado automaticamente e retornado na resposta.

Veja Validacao de Webhooks para exemplos de como verificar a assinatura.

URLs HTTP

Por padrao, webhooks exigem HTTPS para garantir a seguranca dos dados em transito. Para utilizar HTTP, envie allow_insecure: true no cadastro do webhook.

Atencao

URLs HTTP transmitem dados sem criptografia. A seguranca e o sigilo das informacoes trafegadas ficam sob inteira responsabilidade do cliente. A Owem Pay realiza a entrega do webhook normalmente, porem nao se responsabiliza por interceptacao ou vazamento de dados em conexoes nao criptografadas.

---

Listar Webhooks

GET /api/external/webhooks

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	String	Sim	ApiKey {client_id}:{client_secret}

Exemplo

curl -X GET https://api.owem.com.br/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Resposta de Sucesso (200)

{
  "worked": true,
  "webhooks": [
    {
      "id": "wh_a1b2c3d4e5f6",
      "url": "https://seusite.com.br/webhook",
      "events": ["pix.charge.paid", "pix.payout.confirmed"],
      "status": "active",
      "created_at": "2026-03-07T15:30:00Z"
    }
  ]
}

---

Remover Webhook

DELETE /api/external/webhooks/:id

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	String	Sim	ApiKey {client_id}:{client_secret}

Path Parameters

Parametro	Tipo	Obrigatorio	Descricao
id	String	Sim	ID do webhook

Exemplo

curl -X DELETE https://api.owem.com.br/api/external/webhooks/wh_a1b2c3d4e5f6 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Resposta de Sucesso (200)

{
  "worked": true
}

Resposta de Erro (404)

{
  "worked": false,
  "detail": "Webhook nao encontrado"
}