Bridge Payments Docs

Appearance

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:

  1. Provider Webhooks - Events from payment providers (Stripe, PayPal, Authorize.net)
  2. 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 ​

ParameterTypeDescription
providerstringFilter by provider (stripe, paypal, authorize_net)
event_typestringFilter by event type
statusstringFilter by status (success, failed)
limitnumberLimit results (default: 100)
offsetnumberOffset 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 ​