Skip to main content
POST
https://sandbox.finhub.cloud
/
api
/
v2.1
/
webhooks
/
subscriptions
Webhooks
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/webhooks/subscriptions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --data '
{
  "url": "<string>",
  "events": [
    {}
  ],
  "secret": "<string>"
}
'
{
  "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"
  }
}

​
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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -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

EventDescription
customer.createdNew customer registered
customer.updatedCustomer data updated
customer.activatedCustomer account activated
customer.suspendedCustomer account suspended

​
Webhook Payload Structure

{
  "id": "evt_12345",
  "type": "customer.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "customerId": "cust_12345",
    "email": "[email protected]",
    "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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "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": "[email protected]"
      }
    },
    "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

StatusDescription
PENDINGDelivery queued
DELIVEREDSuccessfully delivered (2xx response)
FAILEDAll retry attempts exhausted
RETRYINGDelivery failed, retrying

​
Response Codes

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