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