Registrar Webhook

Endpoints para crear, listar y eliminar webhooks de notificacion.

---

Crear Webhook

POST /api/external/webhooks

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}
Content-Type	String	Si	application/json
hmac	String	Si	Firma HMAC-SHA512 del body (mas informacion)

Request Body

Campo	Tipo	Obligatorio	Por defecto	Descripcion
url	String	Si	--	URL para recibir notificaciones (HTTPS por defecto)
events	Array	No	todos	Lista de eventos a suscribir. Si se omite, suscribe a todos.
allow_insecure	boolean	No	false	Permite URLs HTTP (no-HTTPS). La seguridad de los datos es responsabilidad del cliente.

Eventos disponibles: pix.charge.created, pix.charge.paid, pix.charge.expired, pix.payout.created, pix.payout.confirmed, pix.payout.failed, pix.payout.returned, pix.refund.requested, pix.refund.completed, pix.return.received, webhook.test

Ejemplo

BODY='{"url":"https://sudominio.com/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"

Respuesta Exitosa (201)

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

Respuesta de Error (422)

{
  "worked": false,
  "detail": "La URL debe usar HTTPS"
}

Solo HTTPS por Defecto

La URL del webhook debe usar HTTPS. Las URLs con HTTP seran rechazadas, a menos que se envie allow_insecure: true al registrar el webhook.

URLs HTTP

Por defecto, los webhooks requieren HTTPS para garantizar la seguridad de los datos en transito. Para utilizar HTTP, active la opcion allow_insecure: true al registrar el webhook.

Atencion

Las URLs HTTP transmiten datos sin cifrado. La seguridad y confidencialidad de la informacion transmitida es responsabilidad exclusiva del cliente. Owem Pay realizara la entrega del webhook normalmente, pero no se responsabiliza por la interceptacion o fuga de datos en conexiones no cifradas.

---

Listar Webhooks

GET /api/external/webhooks

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}

Ejemplo

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

Respuesta Exitosa (200)

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

---

Eliminar Webhook

DELETE /api/external/webhooks/:id

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}

Parametros de Ruta

Parametro	Tipo	Obligatorio	Descripcion
id	String	Si	ID del webhook

Ejemplo

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

Respuesta Exitosa (200)

{
  "worked": true
}

Respuesta de Error (404)

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