Skip to main content

​
Overview

Coinut sends webhook events to your registered callback URL when important events occur. All webhooks:
  • Use the POST method
  • Send a JSON body
  • Expect an HTTP 200 response within 30 seconds
  • Use the WebhookEvent envelope documented in rampdocs.json

​
Setting Up Webhooks

1

Register callback URL

Send POST /callback-url with your HTTPS endpoint.
{
  "callbackUrl": "https://your-domain.com/webhooks/coinut"
}
2

Subscribe to events

Send POST /subscribed-events with the event types you want to receive.
{
  "events": [
    "CUSTOMER_APPROVED",
    "DEPOSIT_RECEIVED",
    "TRADE_SETTLED"
  ]
}
3

Verify signature

rampdocs.json does not define a webhook signature header or verification algorithm. If Coinut enables signed webhooks for your environment, follow the latest operational guidance provided with your partner account.
4

Acknowledge receipt

Return HTTP 200 within 30 seconds. The exact retry policy is not defined in rampdocs.json, so your handler should be idempotent and safe to receive duplicate deliveries.

​
Webhook Delivery

PropertyValue
MethodPOST
ProtocolHTTPS only
Timeout30 seconds
RetriesNot specified in rampdocs.json
BackoffNot specified in rampdocs.json
Deduplicationevent + payload combination

​
Event Types

EventDescriptionPayload Type
CUSTOMER_APPROVEDCustomer KYC approvedGetCustomerDataDto
CUSTOMER_REJECTEDCustomer KYC rejectedGetCustomerDataDto
CUSTOMER_DELETEDCustomer deletedGetCustomerDataDto
VIRTUAL_ACCOUNT_APPROVEDVA created and verifiedVirtualAccountDetailDto
VIRTUAL_ACCOUNT_REJECTEDVA creation rejectedVirtualAccountDetailDto
DEPOSIT_ADDRESS_APPROVEDDeposit address verifiedDepositAddressDetailDto
DEPOSIT_ADDRESS_REJECTEDDeposit address rejectedDepositAddressDetailDto
DEPOSIT_RECEIVEDDeposit detectedPartnerDepositDetailDataDto
DEPOSIT_APPROVEDDeposit confirmedPartnerDepositDetailDataDto
DEPOSIT_REJECTEDDeposit rejected/refundedPartnerDepositDetailDataDto
TRADE_CREATEDTrade initiatedTradeDetailDataDto
TRADE_SETTLEDTrade completedTradeDetailDataDto
PAYMENT_SETTLEDPayment completedGetPaymentDetailDataDto

​
Webhook Payload Examples

{
  "event": "CUSTOMER_APPROVED",
  "payload": {
    "id": "6ac34182-aa2e-4290-ab1b-302a09f451d1",
    "realName": "Alice Smith",
    "email": "user@example.com",
    "externalId": "partner-customer-001",
    "sumsubLink": "https://in.sumsub.com/websdk/p/sbx_4pe01gDQ0uXG5lVw",
    "status": "CONFIRMED"
  }
}

​
Signature Verification

rampdocs.json does not define a webhook signature header or signature-construction method. If your partner setup includes signed webhook delivery, use Coinut’s current operational guidance for header names, canonicalization rules, and retry handling.

​
Best Practices

  • Verify signatures when enabled. If Coinut provides a webhook signature mechanism for your environment, validate it before processing the payload.
  • Handle idempotently. Use the event + payload.id combination to prevent duplicate processing.
  • Return 200 quickly. Respond immediately, then process the event asynchronously.
  • Log everything. Store raw payloads and headers for debugging.
  • Expect retries. The same event may arrive multiple times if your handler is slow.
Test webhooks locally with ngrok. Run ngrok http 3000, then register the HTTPS tunnel URL as your callback endpoint. Coinut will deliver events to your local machine.