Skip to main content

Webhooks

Computers use webhooks to communicate with each other about events. Like notifications, webhooks let you know when something you're interested in happens with your integration.

Overview

You're aware of events you request or that your user's request directly from you. Consider the basic API flow for reference. However, not all events are under your control; some events are triggered by external parties. When external events occur, resources are updated in Swan, but you aren't notified by default.

If you subscribe to webhooks for these external events, Swan initiates a request on your endpoint and you receive webhook notifications. Requests to your endpoint must be answered with a 200 OK HTTP response.

Response time

Webhooks operate with a near-real-time efficiency, typically delivering responses within seconds of the event.

It's worth clarifying that webhooks don't actively respond but autonomously send information to your system, potentially introducing delays of up to 10 minutes after the actual action occurs.

Automatic retry

If Swan encounters an error during a webhook request, the request is retried every 30 seconds and up to 7 times.

If all retries fail, you can retry it manually by selecting Retry from your Dashboard > Developers > Webhooks. You can also trigger the webhook manually at any time.

Subscription limits

In order to avoid overconsumption caused by too many subscriptions to the same webhook event, there's a limit on how many subscriptions you can enable per event. Please consider unsubscribing if you have multiple subscriptions to the same event.

The following limits apply:

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

All webhook subscriptions enabled before these limits were established remain intact. However, you won't be able to add additional subscriptions for the same event.

For example, if you had 12 subscriptions to a Sandbox event:

  • All 12 subscriptions remain active.
  • To add a new subscription to that event, delete 3 existing subscriptions first.

Security

Webhooks aren't the most secure communication method, and banking data can be sensitive. Therefore, Swan never uses webhooks to send sensitive information that requires authentication to view.

If an event involves sensitive information, the webhook only includes a notification that an event occurred. You need to use your Dashboard or the API to actually review the information.

Swan's webhook IP addresses

If you have security restrictions in your infrastructure, you might need to add the following IPs to your allowlist for both Sandbox and Live environments.

  • 52.210.172.90
  • 52.51.125.72
  • 54.194.47.212

Event handling

Handling webhooks is important to make sure your integration's business logic works as expected.

Delivery method

Swan webhooks are designed following the at-least once delivery method. Taking transactions as an example, the at-least once delivery means that for the same eventId, you might receive more than one notification.

Swan chose at-least once delivery deliberately over the at-most once delivery; it's better you receive the information multiple times instead of not at all, which can occur with at-most once in case of technical error.

Notification content

Webhook notifications contain the following information in a POST request:

{
"eventType": "Transaction.Booked",
"eventId": "$YOUR_EVENT_ID",
"eventDate": "2021-08-18T09:35:46.673Z",
"projectId": "$YOUR_PROJECT_ID",
"resourceId": "$YOUR_RESOURCE_ID"
}

Note that eventType is the action performed on which resource type, eventId is a unique ID for this event, and resourceId is a unique ID for the resource.

Limited information

For security reasons, webhook notifications include limited information. You can always query the API for more information about these events.

Idempotent process

Due to at-least once delivery, a webhook endpoint might receive the same event notification multiple times. Therefore, Swan strongly suggests making your event processing idempotent, essentially making sure your response to webhook notifications can be repeated multiple times without producing different outcomes.

For example, you might log the events you've processed, and then not process events that are already logged.

Manage webhooks with the API

You can manage your webhooks with the API.

  1. Add a new webhook subscription: addWebhookSubscription.
  2. Update a webhook subscription: updateWebhookSubscription.
  3. Remove a webhook subscription: removeWebhookSubscription.
  4. Trigger a retry of a failed webhook: replayWebhookEvent.
  5. Subscriptions:
    1. Get a single subscription: webhookSubscription.
    2. Get a list of all subscriptions: webhookSubscriptions.
  6. Event logs:
    1. Get one event log: webhookEventLog.
    2. Get a log of all events: webhookEventLogs.

Event order

Webhook notifications aren't always delivered in the order the events occur. If you want to receive webhooks in a specific order, you'll need to implement logic on your end.

For example, consider the regular card payment flow, which is always Authorization to Debit to Released. The flow generates the following webhook events:

  • Authorization: Transaction.Pending
  • Debit: Transaction.Booked
  • Released: Transaction.Released

You'll receive the Transaction.Pending as soon as the authorization is created.

However, you can receive Transaction.Booked and Transaction.Released webhooks in any order, even though the flow is always Debit, then Released.

List of webhook events

The first part of the eventType will tell you what resources to query in an API call. In the following table, you will find all the event types and examples of their functional triggers.

Account holders

eventTypeExplanation
AccountHolder.CreatedOnboarding was finalized
AccountHolder.UpdatedSwan updated a banking verification status

Account onboarding

eventTypeExplanation
Onboarding.CreatedNew onboarding was created either through the API or the no-code interface
Onboarding.UpdatedOnboarding was either finalized, or changed because new data was added to it

Account memberships

eventTypeExplanation
AccountMembership.BoundUser was bound with the account membership
AccountMembership.CreatedNew account membership was created
AccountMembership.DisabledAccount membership was disabled
AccountMembership.ResumedSuspended account membership was resumed
AccountMembership.SuspendedAccount membership was suspended
AccountMembership.UpdatedAccount membership was updated by an action

Accounts

eventTypeExplanation
Account.CreatedOnboarding was finalized
Account.UpdatedAccount attribute was changed
Account.ClosingAccount is closing
Account.ClosedAccount was closed
AccountStatement.GeneratedAccount statement was generated and available for download

Billing

eventTypeExplanation
AccountInvoice.GeneratedNew invoice was generated and available for download
AccountInvoice.UpdatedInvoice or refund note was updated

Capital deposits

eventTypeExplanation
CapitalDepositCaseEvent.CreatedCapital deposit case was created
CapitalDepositCaseEvent.UpdatedCapital deposit case was updated
CapitalDepositDocument.CreatedDocument for a capital deposit case or a shareholder was created
CapitalDepositDocument.UpdatedDocument for a capital deposit case or a shareholder was updated
Shareholder.CreatedShareholder was created
Shareholder.UpdatedShareholder was updated

Cards

eventTypeExplanation
Card.CreatedNew virtual card was created
Card.UpdatedPhysical card was printed, spending limit was updated, and more (doesn't not include PIN notifications)
eventTypeExplanation
Consent.CanceledConsent was canceled by the Partner
Consent.CreatedConsent was created for a sensitive operation
Consent.ExpiredConsent expired without being refused or granted
Consent.GrantedUser accepted a sensitive operation
Consent.RefusedUser refused a sensitive operation
Consent.StartedConsentURL was opened

Funding

eventTypeExplanation
FundingLimitSettingsChangeRequest.CreatedFunding limit settings change request was created
FundingLimitSettingsChangeRequest.UpdatedFunding limit settings change request was updated
FundingSource.CreatedFunding source was created
FundingSource.UpdatedFunding source was updated

Merchants

eventTypeExplanation
MerchantProfile.CreatedMerchant profile was created
MerchantProfile.UpdatedMerchant profile was updated

Payments

eventTypeExplanation
ReceivedDirectDebitMandate.CreatedReceived direct debit mandate was created either through the API or automatically by Swan
ReceivedDirectDebitMandate.UpdatedReceived direct debit mandate was updated
StandingOrder.CanceledStanding order was canceled
StandingOrder.ScheduledStanding order was scheduled

Supporting documents

eventTypeExplanation
SupportingDocumentCollection.CreatedA new supporting document collection was created
SupportingDocumentCollection.UpdatedA supporting document collection was either finalized or updated

Transactions

eventTypeExplanation
Transaction.BookedTransaction was completed and will appear on the account statement
Transaction.CanceledUpcoming direct debit was canceled
Transaction.DeletedScheduled direct debit was deleted
Transaction.EnrichedEnriched transaction information was received for a card transaction outside of a status update
Transaction.PendingOutgoing SEPA Credit Transfer was processed and is waiting for the next SEPA batch, a card authorization was accepted, and more
Transaction.RejectedTransaction was rejected for compliance reasons
Transaction.ReleasedTransaction was released
Transaction.UpcomingTransaction was booked for a future date
TransactionStatement.GeneratedTransaction statement was generated successfully

Users

eventTypeExplanation
User.JoinedUser joins your project
User.UpdatedUser's information was updated, such as their phone number
User.DeactivatedUser was deactivated

The phone number associated with the deactivated user's Swan account can now be used to sign up a different user.