Webhooks

Configure and manage webhooks to receive real-time notifications for events.

Base URL: https://sandbox.finhub.cloud/api/v2.1/webhooks

Available Endpoints

Create Subscription

POST /webhooks/subscriptions

List Subscriptions

GET /webhooks/subscriptions

Get Subscription

GET /webhooks/subscriptions/{id}

Update Subscription

PUT /webhooks/subscriptions/{id}

Delete Subscription

DELETE /webhooks/subscriptions/{id}

Get Deliveries

GET /webhooks/subscriptions/{id}/deliveries

Get Delivery Details

GET /webhooks/deliveries/{deliveryId}

Register Webhook Endpoint

Authorization

string

required

Bearer token for authentication

X-Tenant-ID

string

required

Tenant identifier

url

string

required

HTTPS URL to receive webhook events

events

array

required

List of event types to subscribe to

secret

string

Shared secret for signature verification

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/webhooks" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "url": "https://your-app.com/webhooks/finhub",
    "events": ["customer.created", "transaction.completed", "verification.approved"],
    "secret": "your_webhook_secret"
  }'

{
  "success": true,
  "data": {
    "webhookId": "wh_12345",
    "url": "https://your-app.com/webhooks/finhub",
    "events": ["customer.created", "transaction.completed", "verification.approved"],
    "status": "active",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Available Events

Customer Events
Transaction Events
Verification Events

Event	Description
`customer.created`	New customer registered
`customer.updated`	Customer data updated
`customer.activated`	Customer account activated
`customer.suspended`	Customer account suspended

Event	Description
`transaction.initiated`	Transfer initiated
`transaction.completed`	Transfer completed successfully
`transaction.failed`	Transfer failed
`transaction.pending`	Transfer requires action

Event	Description
`verification.submitted`	Verification documents submitted
`verification.approved`	Verification approved
`verification.rejected`	Verification rejected
`verification.expired`	Verification documents expired

Webhook Payload Structure

{
  "id": "evt_12345",
  "type": "customer.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "customerId": "cust_12345",
    "email": "user@example.com",
    "status": "PENDING_VERIFICATION"
  }
}

Signature Verification

Always verify webhook signatures to ensure requests are from FinHub.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/finhub', (req, res) => {
  const signature = req.headers['x-finhub-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    'your_webhook_secret'
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook event
  console.log('Event:', req.body.type);
  res.status(200).send('OK');
});

Best Practices

Respond Quickly

Return 200 within 5 seconds. Process async if needed.

Handle Retries

Implement idempotency. FinHub retries failed deliveries.

Verify Signatures

Always validate the X-FinHub-Signature header.

Use HTTPS

Webhook URLs must use HTTPS.

Subscription Management

List Subscriptions

Retrieves all webhook subscriptions for your tenant.

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/webhooks/subscriptions" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

{
  "success": true,
  "data": {
    "subscriptions": [
      {
        "subscriptionId": "sub_12345",
        "url": "https://your-app.com/webhooks/finhub",
        "events": ["customer.created", "transaction.completed"],
        "status": "ACTIVE",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      {
        "subscriptionId": "sub_67890",
        "url": "https://your-app.com/webhooks/alerts",
        "events": ["verification.rejected"],
        "status": "ACTIVE",
        "createdAt": "2024-01-10T09:00:00Z"
      }
    ]
  }
}

Get Subscription Details

Retrieves details for a specific webhook subscription.

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/webhooks/subscriptions/sub_12345" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

{
  "success": true,
  "data": {
    "subscriptionId": "sub_12345",
    "url": "https://your-app.com/webhooks/finhub",
    "events": ["customer.created", "transaction.completed"],
    "status": "ACTIVE",
    "secret": "wh_sec_***************",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Update Subscription

Updates an existing webhook subscription.

curl -X PUT "https://sandbox.finhub.cloud/api/v2.1/webhooks/subscriptions/sub_12345" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "url": "https://your-app.com/webhooks/v2/finhub",
    "events": ["customer.created", "customer.updated", "transaction.completed"]
  }'

{
  "success": true,
  "data": {
    "subscriptionId": "sub_12345",
    "url": "https://your-app.com/webhooks/v2/finhub",
    "events": ["customer.created", "customer.updated", "transaction.completed"],
    "status": "ACTIVE",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Delete Subscription

Deletes a webhook subscription.

curl -X DELETE "https://sandbox.finhub.cloud/api/v2.1/webhooks/subscriptions/sub_12345" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

{
  "success": true,
  "data": {
    "subscriptionId": "sub_12345",
    "status": "DELETED",
    "deletedAt": "2024-01-15T12:00:00Z"
  }
}

Delivery History

Get Subscription Deliveries

Retrieves delivery history for a webhook subscription.

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/webhooks/subscriptions/sub_12345/deliveries" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

{
  "success": true,
  "data": {
    "subscriptionId": "sub_12345",
    "deliveries": [
      {
        "deliveryId": "del_001",
        "eventId": "evt_12345",
        "eventType": "customer.created",
        "status": "DELIVERED",
        "responseCode": 200,
        "attempts": 1,
        "deliveredAt": "2024-01-15T10:30:05Z"
      },
      {
        "deliveryId": "del_002",
        "eventId": "evt_67890",
        "eventType": "transaction.completed",
        "status": "FAILED",
        "responseCode": 500,
        "attempts": 3,
        "lastAttemptAt": "2024-01-15T11:00:00Z",
        "nextRetryAt": "2024-01-15T11:30:00Z"
      }
    ]
  }
}

Get Delivery Details

Retrieves full details of a specific delivery including payload.

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/webhooks/deliveries/del_001" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

{
  "success": true,
  "data": {
    "deliveryId": "del_001",
    "subscriptionId": "sub_12345",
    "eventId": "evt_12345",
    "eventType": "customer.created",
    "url": "https://your-app.com/webhooks/finhub",
    "status": "DELIVERED",
    "payload": {
      "id": "evt_12345",
      "type": "customer.created",
      "timestamp": "2024-01-15T10:30:00Z",
      "data": {
        "customerId": "cust_12345",
        "email": "user@example.com"
      }
    },
    "requestHeaders": {
      "Content-Type": "application/json",
      "X-FinHub-Signature": "sha256=..."
    },
    "responseCode": 200,
    "responseBody": "OK",
    "responseTime": 125,
    "attempts": [
      {
        "attemptNumber": 1,
        "timestamp": "2024-01-15T10:30:05Z",
        "responseCode": 200,
        "success": true
      }
    ]
  }
}

Delivery Statuses

Status	Description
`PENDING`	Delivery queued
`DELIVERED`	Successfully delivered (2xx response)
`FAILED`	All retry attempts exhausted
`RETRYING`	Delivery failed, retrying

Response Codes

Code	Description
`200`	Operation successful
`201`	Webhook created successfully
`400`	Invalid request data
`401`	Unauthorized
`404`	Subscription not found
`500`	Internal server error

Headers

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

X-User-ID

string

Authenticated user identifier

Example:

"87b3af37-4ac1-402b-a0ea-53cfdc695e02"

Body

application/json

customerId

string

subscriptionName

string

description

string

endpointUrl

string

secretKey

string

signatureAlgorithm

string

verifySsl

boolean

subscribedEvents

string[]

maxRetryAttempts

integer<int32>

retryBackoffSeconds

integer<int32>

Response

200

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Webhooks

Webhooks

Available Endpoints

Create Subscription

List Subscriptions

Get Subscription

Update Subscription

Delete Subscription

Get Deliveries

Get Delivery Details

Register Webhook Endpoint

Code Examples

Available Events

Webhook Payload Structure

Signature Verification

Best Practices

Respond Quickly

Handle Retries

Verify Signatures

Use HTTPS

Subscription Management

List Subscriptions

Get Subscription Details

Update Subscription

Delete Subscription

Delivery History

Get Subscription Deliveries

Get Delivery Details

Delivery Statuses

Response Codes

Headers

Body

Response

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Webhooks

​Available Endpoints

Create Subscription

List Subscriptions

Get Subscription

Update Subscription

Delete Subscription

Get Deliveries

Get Delivery Details

​Register Webhook Endpoint

​Code Examples

​Available Events

​Webhook Payload Structure

​Signature Verification

​Best Practices

Respond Quickly

Handle Retries

Verify Signatures

Use HTTPS

​Subscription Management

​List Subscriptions

​Get Subscription Details

​Update Subscription

​Delete Subscription

​Delivery History

​Get Subscription Deliveries

​Get Delivery Details

​Delivery Statuses

​Response Codes

Headers

Body

Response

Webhooks

Available Endpoints

Register Webhook Endpoint

Code Examples

Available Events

Webhook Payload Structure

Signature Verification

Best Practices

Subscription Management

List Subscriptions

Get Subscription Details

Update Subscription

Delete Subscription

Delivery History

Get Subscription Deliveries

Get Delivery Details

Delivery Statuses

Response Codes