Skip to main content
Webhooks allow you to receive real-time notifications when events happen on your Platform. Instead of polling the API, you can configure a URL that Otim will send POST requests to whenever a relevant event occurs.

​
Setup

Configure your webhook URL via the Update Platform Settings endpoint: 
curl -X PATCH https://api.otim.com/v0/platform/settings \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://yourapp.com/webhooks/otim"
  }'
Set webhookUrl to null to disable webhooks.

​
Payload format

All webhook payloads follow the same structure: 
{
  "id": "evt_01JA1B2C3D4E5F6G7H8J9K0L",
  "type": "transfer.completed",
  "createdAt": "2025-01-15T12:00:00Z",
  "data": { }
}
FieldTypeDescription
idstringUnique identifier for the event.
typestringThe event type.
createdAtstringISO 8601 timestamp of when the event occurred.
dataobjectThe full object associated with the event.

​
Event types

​
Transfers

EventDescription
transfer.createdA new transfer has been initiated.
transfer.processingThe transfer is being processed.
transfer.completedThe transfer has completed successfully.
transfer.failedThe transfer has failed.

​
Entities

EventDescription
entity.kyc.approvedAn Entity has passed identity verification.
entity.kyc.rejectedAn Entity’s identity verification was rejected.
entity.tos.approvedAn Entity has accepted the terms of service.

​
Accounts

EventDescription
account.createdA new Account has been provisioned.

​
IBANs

EventDescription
iban.deposit.receivedA fiat deposit has been received at an IBAN and routed to the linked Account.

​
Responding to webhooks

Your endpoint should return a 200 status code within 10 seconds. If Otim does not receive a 200 response, the webhook will be retried up to 5 times with exponential backoff.

​
Verifying signatures

Each webhook request includes a X-Otim-Signature header containing an HMAC-SHA256 signature of the request body. Verify this signature to ensure the request came from Otim. 
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Your webhook signing secret is available in the Developer section of your dashboard.