Webhook Endpoints

Manage webhook endpoints to receive real-time event notifications

List Webhook Endpoints

Retrieve a list of all webhook endpoints configured for your instance.

const response = await blindpay.webhookEndpoints.list();

Response

data · array

Array of webhook endpoint objects

Show Webhook Endpoint object

id · string · required

Unique identifier for the webhook endpoint

url · string · required

The HTTPS URL where webhook events are sent

events · array · required

Array of event types this endpoint subscribes to. See Webhook Events for available types

last_event_at · string · required

ISO 8601 timestamp of when the last event was sent to this endpoint

instance_id · string · required

ID of the instance this endpoint belongs to

created_at · string · required

ISO 8601 timestamp of when the endpoint was created

updated_at · string · required

ISO 8601 timestamp of when the endpoint was last updated

{
  "data": [
    {
      "id": "whep_1234567890",
      "url": "https://api.example.com/webhooks/blindpay",
      "events": ["payout.new", "payout.complete", "payin.new", "payin.complete"],
      "last_event_at": "2024-03-01T15:30:00Z",
      "instance_id": "inst_1234567890",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "error": null
}

Create Webhook Endpoint

Create a new webhook endpoint to receive event notifications.

const response = await blindpay.webhookEndpoints.create({
  url: "https://api.example.com/webhooks/blindpay",
  events: ["payout.new", "payout.complete", "payin.new", "payin.complete"]
});

Parameters

url · string · required

The HTTPS URL where webhook events will be sent. Must use HTTPS protocol

events · array · required

Array of event types to subscribe to. See Webhook Events for available types

Response

data · object

Show Create Webhook Endpoint Response

id · string · required

Unique identifier for the created webhook endpoint

{
  "data": {
    "id": "whep_1234567890"
  },
  "error": null
}

Delete Webhook Endpoint

Permanently delete a webhook endpoint.

const response = await blindpay.webhookEndpoints.delete("whep_1234567890");

Parameters

id · string · required

The ID of the webhook endpoint to delete

Response

Returns a success response with no data on successful deletion.

{
  "data": null,
  "error": null
}

Get Webhook Endpoint Secret

Retrieve the signing secret for a webhook endpoint. Use this secret to verify that webhook events are genuinely from BlindPay.

const response = await blindpay.webhookEndpoints.getSecret("whep_1234567890");

Parameters

id · string · required

The ID of the webhook endpoint

Response

data · object

Show Webhook Secret Response

key · string · required

The signing secret for this webhook endpoint

{
  "data": {
    "key": "whsec_abcdefghijklmnopqrstuvwxyz123456"
  },
  "error": null
}

Get Portal Access URL

Retrieve a URL to access the Svix webhook portal, where you can view webhook delivery history and retry failed deliveries.

const response = await blindpay.webhookEndpoints.getPortalAccessUrl();

Response

data · object

Show Portal Access Response

url · string · required

URL to access the webhook portal

{
  "data": {
    "url": "https://portal.svix.com/login?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "error": null
}

Webhook Events

The following event types are available for webhook subscriptions:

Receiver Events

• receiver.new - A new receiver has been created
• receiver.update - A receiver’s information has been updated

Bank Account Events

• bankAccount.new - A new bank account has been added

Payout Events

• payout.new - A new payout has been initiated
• payout.update - A payout’s status has been updated
• payout.complete - A payout has been completed
• payout.partnerFee - A partner fee has been processed for a payout

Payin Events

• payin.new - A new payin has been initiated
• payin.update - A payin’s status has been updated
• payin.complete - A payin has been completed
• payin.partnerFee - A partner fee has been processed for a payin

Blockchain Wallet Events

• blockchainWallet.new - A new blockchain wallet has been created

Terms of Service Events

• tos.accept - Terms of service have been accepted

Verifying Webhook Signatures

To ensure webhook events are genuinely from BlindPay, verify the signature included in the webhook headers:

import { Webhook } from 'svix';

const webhook = new Webhook(webhookSecret);

try {
  const payload = webhook.verify(
    request.body,
    request.headers
  );
  // Process the verified payload
} catch (err) {
  // Signature verification failed
  console.error('Webhook signature verification failed:', err);
}

Best Practices

Follow these best practices when working with webhooks:

• Use HTTPS - Always use HTTPS URLs for webhook endpoints
• Verify signatures - Always verify webhook signatures to ensure authenticity
• Handle idempotency - Webhook events may be delivered more than once. Use event IDs to handle duplicates
• Respond quickly - Return a 200 status code within 5 seconds to avoid timeouts
• Process asynchronously - Queue webhook events for processing rather than handling them synchronously
• Monitor failures - Use the portal access URL to monitor and retry failed deliveries
• Subscribe selectively - Only subscribe to events you need to reduce unnecessary traffic