Webhooks allow your application to receive real-time updates when events occur in the system—without needing to continuously poll APIs.

Instead of making repeated API calls (pull), webhooks deliver event data directly to your system (push), making integrations more efficient, scalable, and responsive.

Common use cases include:

• Transaction declines or approvals
• Settlement updates
• Card lifecycle events

How Webhooks Work

Webhooks follow a simple event-driven flow:

1. Subscribe to Events Register the events you want to receive and provide a secure HTTPS endpoint
2. Event Occurs An event is triggered in the system (e.g., transaction declined)
3. Webhook Sent A JSON payload is delivered via HTTP POST to your endpoint
4. Process & Acknowledge Your system validates and processes the event

Set Up a Webhook Subscription

Follow these steps to configure webhook notifications:

1. Discover Available Events

Before subscribing, review the list of supported events listed on Webhook Events page.

This helps you identify which events are relevant to your use case.

2. Create a Subscription

Use the POST /v1/customer/id/{id}/webhookSubscription API endpoint to register a webhook by providing following key parameters:

You can subscribe to multiple event types across customers, accounts, transactions, and cards in a single webhook.

3. Retrieve Subscription Details

After creating a webhook, use the GET /v1/customer/id/{id}/webhookSubscription/id/{id} API endpoint, to verify its configuration:

• Confirm subscribed events
• Validate endpoint configuration
• Check current status

4. Enable or Disable a Subscription

Control whether your webhook actively receives events:

• Enable Webhook POST /v1/customer/id/{id}/webhookSubscription/id/{id}/enable
• Disable Webhook POST /v1/customer/id/{id}/webhookSubscription/id/{id}/disable

This is useful for:

• Temporarily pausing event delivery
• Testing new configurations safely

How to Think About Webhook Setup

• Create → Configure → Enable
• One webhook can handle multiple event types
• Use enable/disable to control event flow without deleting configuration

sequenceDiagram
    participant You as Your Platform
    participant PCE as PCE API
    participant WH as Your Webhook Endpoint

    You->>PCE: POST /webhookSubscription (subscribe to events)
    PCE-->>You: Subscription created (id, status)
    You->>PCE: POST .../enable
    PCE-->>You: Subscription active
    Note over PCE: Event occurs (e.g. transaction created)
    PCE->>WH: HTTP POST (JSON payload)
    WH-->>PCE: 200 OK (acknowledged)
    WH->>You: Process event (update UI, trigger workflow)

Common Integration Scenarios

Scenario 1: Set up real-time transaction monitoring for a payments platform

A lending platform wants to receive instant notifications whenever a transaction is created, updated, or completed, so it can update customer balances and trigger downstream workflows in real time.

Steps:

1. Create a webhook subscription via POST /v1/customer/id/{id}/webhookSubscription with:
   • url: Your HTTPS endpoint (e.g., https://api.yourplatform.com/webhooks/treasury)
   • subscribedEventType: ["transaction.ach.create", "transaction.ach.update", "transaction.wire.create", "transaction.wire.update"]
2. Verify the subscription is active using GET /v1/customer/id/{id}/webhookSubscription/id/{id}.
3. When a transaction is created or its status changes, your endpoint receives a JSON payload with the full transaction resource.
4. Your system validates the payload, updates the customer's dashboard, and triggers any downstream processing (e.g., ledger updates, notifications).

Scenario 2: Monitor card lifecycle events for a neobank app

A neobank wants to push real-time card status updates to its mobile app, so customers see instant notifications when their card is activated, frozen, or cancelled.

Steps:

1. Create a webhook subscription with:
   • subscribedEventType: card issuance lifecycle events (e.g., card create, card update)
2. Enable the subscription.
3. When a card status changes (e.g., PENDING → ACTIVE, ACTIVE → FREEZED), your endpoint receives the event.
4. Your mobile app pushes a notification to the customer: "Your card is now active and ready to use."

Scenario 3: Temporarily pause webhooks during a maintenance window

Your platform has a scheduled maintenance window and you need to stop receiving webhook events temporarily without losing your subscription configuration.

Steps:

1. Disable the webhook via POST /v1/customer/id/{id}/webhookSubscription/id/{id}/disable.
2. Events that occur during the maintenance window will not be delivered.
3. After maintenance, re-enable the webhook via POST /v1/customer/id/{id}/webhookSubscription/id/{id}/enable.
4. Use list or GET APIs to reconcile any events that occurred during the downtime.