Skip to main content

2. Webhooks Overview

Swan's webhook system delivers instant notifications when banking events occur, eliminating polling delays and keeping your business synchronized in real-time.

Business Value​

Webhooks instantly notify your system when transactions complete, cards are used, or accounts change status. This enables immediate customer updates and automated workflows.

Key Benefits
  • Instant awareness - React to banking events as they happen
  • Automated operations - Trigger fulfillment, notifications, and reporting instantly
  • Reduced API costs - Eliminates expensive polling requests
  • Better customer experience - Immediate notifications and status updates

Technical Implementation​

How Swan Webhooks Work​

Swan webhooks are HTTP POST notifications containing minimal event metadata.

Your application receives a lightweight notification, acknowledges receipt with HTTP 200, then queries Swan's GraphQL API for complete details.


Practical Example​


Webhook Payload Structure​

Swan webhook notifications contain only generic event metadata:

{
  "eventType": "Transaction.Booked",
  "eventId": "evt_01HQ7ZXM8KH9EXAMPLE", 
  "eventDate": "2024-01-15T14:30:00Z",
  "projectId": "prj_01HQ7ZXM8KH9EXAMPLE",
  "resourceId": "T_01HQ7ZXM8KH9EXAMPLE"
}
Important

For security reasons, Swan webhooks never contain any transaction amounts, account details, or other sensitive information. You must query the API using the resourceId for complete data.


Payment Flow Examples​

SEPA Credit Transfer Success​

Business Scenario: Customer pays invoice via bank transfer

  1. Webhook received: Transaction.Booked event with transaction ID
  2. API query: Fetch transaction details including amount and reference
  3. Business action: Trigger automated fulfillment workflow

Direct Debit Failure​

Business Scenario: Subscription payment fails

  1. Webhook received: Transaction.Rejected event
  2. API query: Reveals rejection reason (e.g., insufficient funds)
  3. Business action: Schedule retry → Send customer notification

Card Payment Authorization​

Business Scenario: Real-time spending notification

  1. Webhook received: Transaction.Pending event
  2. API query: Get merchant and amount details
  3. Business action: Send instant spending alert

Implementation Best Practices​

Idempotent Processing​

Swan uses at-least once delivery, which means you may receive the same webhook multiple times.
Always implement idempotent processing using the eventId as your unique key.

// javascript example
async function isEventProcessed(eventId) {
  return processedEvents.has(eventId);
}

Error Handling​

Acknowledgement is critical

Always return HTTP success code 200 to acknowledge receipt, even if processing fails.

Any other status code triggers Swan's retry mechanism (every 30 seconds, up to 7 times).


Swan-Specific Considerations​

Security Model​

Swan webhooks require no signature verification because they contain no sensitive data.

Security comes from:

  • Minimal payloads (metadata only)
  • Authenticated API queries for actual data
  • HTTPS endpoints required

Event Ordering​

Webhooks may arrive out of order.

For instance, a card payment generates Transaction.Pending → Transaction.Booked → Transaction.Released, but you might receive them in any sequence.


Subscription Limits​

  • Sandbox: 10 subscriptions per event type
  • Live: 5 subscriptions per event type

Implementation Steps​

  1. Configure webhook endpoint in Swan Dashboard
  2. Implement handler following notification + API query pattern
  3. Deploy idempotent processing for duplicate handling
  4. Test with Event Simulator in Dashboard

Resources: