Register Webhook

Endpoints to create, list, and remove notification webhooks.

---

Create Webhook

POST /api/external/webhooks

Headers

Header	Type	Required	Description
Authorization	String	Yes	ApiKey {client_id}:{client_secret}
Content-Type	String	Yes	application/json
hmac	String	Yes	HMAC-SHA512 signature of the body (learn more)

Request Body

Field	Type	Required	Default	Description
url	String	Yes	--	URL to receive notifications (HTTPS by default)
events	Array	No	all	List of events to subscribe to. If omitted, subscribes to all.
allow_insecure	boolean	No	false	Allow HTTP (non-HTTPS) URLs. Security risk is client's responsibility.

Available events:

Event	Description
pix.charge.created	QR code generated
pix.charge.paid	PIX received and settled
pix.charge.expired	QR code expired (24h)
pix.payout.processing	PIX sent, awaiting confirmation
pix.payout.confirmed	PIX sent and confirmed
pix.payout.failed	PIX sent rejected
pix.payout.returned	PIX sent returned
pix.refund.requested	MED received, funds blocked
pix.refund.completed	MED finalized
pix.return.received	PIX return received (credit)
webhook.test	Manual test

Example

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

Success Response (201)

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

Error Response (422)

{
  "worked": false,
  "detail": "URL must use HTTPS"
}

HTTPS Only by Default

The webhook URL must use HTTPS. HTTP URLs will be rejected unless allow_insecure: true is sent when creating the webhook.

Important — Webhook Secret

The secret field returned in the creation response is the key used to sign webhook deliveries (HMAC-SHA256). Store this value securely — it will not be shown again.

Do NOT confuse with client_secret:

• client_secret = authentication for your API requests (Authorization header)
• Webhook secret = verification of received delivery signatures (X-Owem-Signature header)

If you do not send the secret field when creating the webhook, a random value will be auto-generated and returned in the response.

See Webhook Validation for examples on how to verify the signature.

HTTP URLs

By default, webhooks require HTTPS to ensure data security in transit. To use HTTP, set allow_insecure: true when creating the webhook.

Warning

HTTP URLs transmit data without encryption. The security and confidentiality of transmitted information is entirely the client's responsibility. Owem Pay will deliver the webhook normally but assumes no liability for interception or data leakage on unencrypted connections.

---

List Webhooks

GET /api/external/webhooks

Headers

Header	Type	Required	Description
Authorization	String	Yes	ApiKey {client_id}:{client_secret}

Example

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

Success Response (200)

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

---

Remove Webhook

DELETE /api/external/webhooks/:id

Headers

Header	Type	Required	Description
Authorization	String	Yes	ApiKey {client_id}:{client_secret}

Path Parameters

Parameter	Type	Required	Description
id	String	Yes	Webhook ID

Example

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

Success Response (200)

{
  "worked": true
}

Error Response (404)

{
  "worked": false,
  "detail": "Webhook not found"
}