Webhooks API

The Webhooks API allows you to receive real-time notifications about payment events from payment providers and configure external webhooks for custom integrations.

Base URL

https://your-instance.pubflow.com/bridge-payment

Webhook Types

Bridge Payments supports two types of webhooks:

Provider Webhooks - Events from payment providers (Stripe, PayPal, Authorize.net)
External Webhooks - Custom webhooks to your own endpoints

Provider Webhooks

Webhook Endpoints

Configure these URLs in your payment provider dashboard:

Stripe:

https://your-instance.pubflow.com/bridge-payment/webhooks/stripe

PayPal:

https://your-instance.pubflow.com/bridge-payment/webhooks/paypal

Authorize.net:

https://your-instance.pubflow.com/bridge-payment/webhooks/authorize-net

Supported Events

Payment Events

payment_intent.succeeded - Payment completed successfully
payment_intent.failed - Payment failed
payment_intent.canceled - Payment canceled
payment_intent.processing - Payment is processing
payment_intent.requires_action - Payment requires customer action (3D Secure)

Payment Method Events

payment_method.attached - Payment method added to customer
payment_method.detached - Payment method removed
payment_method.updated - Payment method details updated

Subscription Events

subscription.created - New subscription created
subscription.updated - Subscription details changed
subscription.deleted - Subscription canceled
subscription.trial_will_end - Trial ending soon (3 days before)
invoice.payment_succeeded - Subscription payment successful
invoice.payment_failed - Subscription payment failed

Customer Events

customer.created - New customer created
customer.updated - Customer details updated
customer.deleted - Customer deleted

Event Payload

json

{
  "id": "evt_1234567890",
  "type": "payment_intent.succeeded",
  "provider": "stripe",
  "data": {
    "object": {
      "id": "pi_stripe_abc123",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded",
      "customer": "cus_stripe_xyz789"
    }
  },
  "created": 1705320600
}

Webhook Security

Bridge Payments automatically verifies webhook signatures from providers:

Stripe: Validates using stripe-signature header
PayPal: Validates using PayPal webhook verification API
Authorize.net: Validates using signature key

External Webhooks

External webhooks allow you to send payment events to your own endpoints (Discord, Slack, custom APIs).

Configuration

Configure external webhooks via environment variables:

bash

# Enable external webhooks
EXTERNAL_WEBHOOKS_ENABLED=true

# Webhook endpoints (comma-separated)
EXTERNAL_WEBHOOK_URLS=https://discord.com/api/webhooks/123,https://api.example.com/webhooks

# Events to send (comma-separated, or "all")
EXTERNAL_WEBHOOK_EVENTS=payment_intent.succeeded,subscription.created

# Retry configuration
EXTERNAL_WEBHOOK_MAX_RETRIES=3
EXTERNAL_WEBHOOK_RETRY_DELAY=5000

# Timeout (milliseconds)
EXTERNAL_WEBHOOK_TIMEOUT=10000

Event Types

All provider events are available for external webhooks:

payment_intent.*
payment_method.*
subscription.*
invoice.*
customer.*

Payload Format

json

{
  "event": "payment_intent.succeeded",
  "provider": "stripe",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "payment_id": "pay_123",
    "amount": 2000,
    "currency": "USD",
    "customer_email": "[email protected]",
    "status": "succeeded"
  }
}

Discord Integration

bash

EXTERNAL_WEBHOOK_URLS=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
EXTERNAL_WEBHOOK_EVENTS=payment_intent.succeeded,subscription.created

Discord Message Format:

💰 Payment Successful
Amount: $20.00 USD
Customer: [email protected]
Status: succeeded
Time: 2025-01-15 10:30:00

Slack Integration

bash

EXTERNAL_WEBHOOK_URLS=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
EXTERNAL_WEBHOOK_EVENTS=payment_intent.succeeded,payment_intent.failed

Slack Message Format:

json

{
  "text": "💰 Payment Successful",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Amount:* $20.00 USD\n*Customer:* [email protected]\n*Status:* succeeded"
      }
    }
  ]
}

Custom API Integration

bash

EXTERNAL_WEBHOOK_URLS=https://api.yourapp.com/webhooks/payments
EXTERNAL_WEBHOOK_EVENTS=all

Custom Endpoint Requirements:

Accept POST requests
Return 200 status code for success
Process within timeout period (default: 10 seconds)
Handle retries gracefully

Webhook Logs

List Webhook Events

http

GET /bridge-payment/webhooks/logs
X-Session-ID: <session_id>

Query Parameters

Parameter	Type	Description
`provider`	string	Filter by provider (stripe, paypal, authorize_net)
`event_type`	string	Filter by event type
`status`	string	Filter by status (success, failed)
`limit`	number	Limit results (default: 100)
`offset`	number	Offset for pagination

Response

json

[
  {
    "id": "log_123",
    "provider": "stripe",
    "event_type": "payment_intent.succeeded",
    "status": "success",
    "payload": { ... },
    "response": { ... },
    "created_at": "2025-01-15T10:30:00Z"
  }
]

Get Webhook Event

http

GET /bridge-payment/webhooks/logs/:id
X-Session-ID: <session_id>

Returns complete webhook event details including payload and response.

Retry Logic

Provider Webhooks

Bridge Payments does not retry provider webhooks. Providers handle retries automatically.

External Webhooks

External webhooks are retried on failure:

Max Retries: 3 (configurable)
Retry Delay: 5 seconds (configurable)
Backoff Strategy: Exponential (5s, 10s, 20s)
Timeout: 10 seconds (configurable)

Retry Configuration

bash

# Maximum retry attempts
EXTERNAL_WEBHOOK_MAX_RETRIES=3

# Initial retry delay (milliseconds)
EXTERNAL_WEBHOOK_RETRY_DELAY=5000

# Request timeout (milliseconds)
EXTERNAL_WEBHOOK_TIMEOUT=10000

Testing Webhooks

Test Provider Webhooks

Use provider testing tools:

Stripe:

bash

stripe trigger payment_intent.succeeded

PayPal: Use PayPal Sandbox webhook simulator

Authorize.net: Use Authorize.net test mode

Test External Webhooks

bash

# Trigger test webhook
curl -X POST "https://your-instance.pubflow.com/bridge-payment/webhooks/test" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "event": "payment_intent.succeeded",
    "test_data": {
      "amount": 2000,
      "currency": "USD"
    }
  }'

Security Best Practices

1. Verify Webhook Signatures

Always verify webhook signatures from providers (Bridge Payments does this automatically).

2. Use HTTPS

Always use HTTPS for webhook endpoints.

3. Validate Event Data

Validate event data before processing:

typescript

if (event.type === 'payment_intent.succeeded') {
  const paymentId = event.data.object.id;
  // Fetch payment from your database to verify
  const payment = await getPayment(paymentId);
  if (payment.status !== 'succeeded') {
    // Update payment status
  }
}

4. Idempotency

Handle duplicate webhook events gracefully:

typescript

const eventId = event.id;
if (await isEventProcessed(eventId)) {
  return; // Already processed
}
await markEventAsProcessed(eventId);
// Process event

5. Monitor Webhook Failures

Monitor webhook logs for failures and investigate issues.

Next Steps

External Webhooks Guide - Detailed external webhook setup
Payments API - Payment events
Subscriptions API - Subscription events

Webhooks API ​

Base URL ​

Webhook Types ​

Provider Webhooks ​

Webhook Endpoints ​

Supported Events ​

Payment Events ​

Payment Method Events ​

Subscription Events ​

Customer Events ​

Event Payload ​

Webhook Security ​

External Webhooks ​

Configuration ​

Event Types ​

Payload Format ​

Discord Integration ​

Slack Integration ​

Custom API Integration ​

Webhook Logs ​

List Webhook Events ​

Query Parameters ​

Response ​

Get Webhook Event ​

Retry Logic ​

Provider Webhooks ​

External Webhooks ​

Retry Configuration ​

Testing Webhooks ​

Test Provider Webhooks ​

Test External Webhooks ​

Security Best Practices ​

1. Verify Webhook Signatures ​

2. Use HTTPS ​

3. Validate Event Data ​

4. Idempotency ​

5. Monitor Webhook Failures ​

Next Steps ​

Webhooks API

Base URL

Webhook Types

Provider Webhooks

Webhook Endpoints

Supported Events

Payment Events

Payment Method Events

Subscription Events

Customer Events

Event Payload

Webhook Security

External Webhooks

Configuration

Event Types

Payload Format

Discord Integration

Slack Integration

Custom API Integration

Webhook Logs

List Webhook Events

Query Parameters

Response

Get Webhook Event

Retry Logic

Provider Webhooks

External Webhooks

Retry Configuration

Testing Webhooks

Test Provider Webhooks

Test External Webhooks

Security Best Practices

1. Verify Webhook Signatures

2. Use HTTPS

3. Validate Event Data

4. Idempotency

5. Monitor Webhook Failures

Next Steps