Webhooks - Kravata Stack

Register a webhook to receive a POST request on your server every time a monitored process changes, for example when an order moves from pending to paidawaitingfunds.

Manage your webhooks

Action	Endpoint
Create	Create Webhook
List	Get Webhooks
Deactivate	Delete Webhook

curl -X POST https://testapi.kravata.co/api/webhooks/YOUR_CLIENT_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.example.com/webhooks/kravata", "process": "ramp" }'

The process can be ramp, compliance or wallet_transfer. The url must start with http:// or https://; use HTTPS in production.

Payload

For the ramp process, the payload contains the complete updated order:

{
  "amountReceived": 2.29,
  "amountSent": 10000.0,
  "bankAccountId": "04637bb8-be4c-4fc7-8312-7b0541736d86",
  "destinationUserId": "20ec3cb9-497c-480f-9478-4d64c7b43064",
  "id": "de98e68a-1051-4803-a1e6-0fda74de333b",
  "numberRamp": "0005277",
  "operationCategory": "ramp",
  "originUserId": "20ec3cb9-497c-480f-9478-4d64c7b43064",
  "rampType": "on_ramp",
  "registerDate": "2025-01-17 16:05:25.873917",
  "status": "paidawaitingfunds",
  "symbolTypeReceived": "USDC",
  "symbolTypeSent": "COP",
  "userId": "20ec3cb9-497c-480f-9478-4d64c7b43064",
  "walletId": "0ed2aa92-da56-4774-847f-6352c8e8e177",
  "rampDetails": {
    "txid": "0x7281e10bc6db3684340b3d53d927cea34312dea3e6c4b8ab926d666d3ffbd46c"
  }
}

Field	Description
id	Identifier of the order.
numberRamp	Sequential tracking number.
rampType	`on_ramp` or `off_ramp`.
status	Current status. See Order statuses.
amountSent / amountReceived	Amounts in the origin and destination assets.
symbolTypeSent / symbolTypeReceived	Origin and destination assets.
bankAccountId / walletId	Bank account and wallet of the order.
registerDate	Creation timestamp.
rampDetails	Additional details, such as the blockchain transaction ID (`txid`).

Respond with a 2xx quickly and process the event asynchronously. Before acting on a critical status, confirm it with Get Ramps.

Security

A webhook is delivered to the URL you registered, over the public internet. Today its authenticity rests on the URL being secret and served over HTTPS — there is no cryptographic signature of the body yet (payload signing is on the roadmap). So:

Treat the webhook URL as a secret and serve it only over HTTPS.
Do not move money or change your own records based only on the webhook body. For any state that matters, confirm the order against the API by its id with Get Ramps before acting — the body is a notification, not proof.
Use the idempotency/order id to ignore duplicate or replayed deliveries.