Webhooks

Oceafin can deliver partner events to a registered HTTPS webhook endpoint.
Webhook delivery is optional and depends on the partner tenant configuration.

Payload Shape

{
  "eventId": "00000000-0000-0000-0000-000000000000",
  "eventType": "conversion.created",
  "customer": {
    "customerId": "00000000-0000-0000-0000-000000000000",
    "partnerCustomerRef": "cust-100001"
  },
  "resource": {
    "resourceType": "conversion",
    "resourceId": "00000000-0000-0000-0000-000000000000"
  },
  "occurredAt": "2026-06-28T00:00:00Z",
  "data": {}
}

Signature Headers

Header	Notes
`X-Oceafin-Webhook-Timestamp`	Offset date-time.
`X-Oceafin-Webhook-Nonce`	Unique nonce for this delivery attempt.
`X-Oceafin-Webhook-Signature`	Lowercase hex HMAC-SHA256 signature.

Signature Base String

timestamp
nonce
bodySha256Hex

Verify the signature with the webhook signing secret provided by Oceafin.

Node.js Verification Example

Use the raw HTTP request body bytes or string exactly as received. Do not
re-serialize parsed JSON before verifying the signature.

Event Types

Currently published event types:

customer.onboarding.submitted

fiat_account.application.submitted

fiat_deposit.completed

fiat_withdrawal.created

crypto.deposit.pending_travel_rule

crypto_withdrawal.created

crypto_checkout.created

collection_wallet.created

crypto_refund.created

conversion.created

customer.transaction.updated

customer.balance.changed

Delivery And Retry

Any HTTP 2xx response is treated as successful delivery. Non-2xx responses
are retried up to the configured attempt limit and then marked failed for
operator inspection.

Webhook handlers should:

Verify the signature before parsing business data.

Store eventId and process each event idempotently.

Return 2xx only after the event is durably accepted.

Avoid long-running work in the webhook request path.

Payload Shape#

Signature Headers#

Signature Base String#

Node.js Verification Example#