Links

Webhooks

Introduction

With our GraphQL API you can request data and perform actions on your accounts, cards, transactions, etc. In this communication process, you (or your user) ask Swan to execute operations and we respond.
How to execute operations with our API
With webhooks, when an external event happens and a resource is updated on our side, we initiate the request to one of your endpoints. This allows you to process events that were not initiated by you - through our API, and in near real-time. Most of the time, few seconds after the event, and sometimes up to 10min.
How to get data using a webhook
Banking data is sensitive; that's why we require authentication to access it! And webhooks simply aren't that secure. So we won't send sensitive banking data through them, you'll just get a notification that something happened. To access sensitive data impacted by an event, you'll need to query our API.

Add and configure a webhook

You can configure a webhook from our dashboard. A webhook object possesses 5 characteristics:
  • status: a webhook can be Enabled or Disabled
  • label: input a short text of your choice
  • endpoint URL: the URL we will request
  • events: the list of event types where we request endpoint URL
  • secret (optional but recommended): UUID Type 4 secret to check all webhooks we sent to the endpoint URL. The maximum length of this secret is 36 characters.
Webhook secret
Though the secret is optional when creating your webhooks, Swan recommends adding a secret for every webhook for increased security. The secret confirms that the webhook call comes from Swan, and you might need it in the HTTP header.
--header 'x-swan-secret: $YOUR_WEBHOOK_SECRET' \
Once a webhook is created, you can get more information on its usage and see all requests up to that point. This allows you to troubleshoot any errors you might encounter and see what Swan got back as a response. You can access filters on the eventId or the resourceId to search for specific events that were fired.
For security reasons, you'll have to manually configure your webhooks. You can do this once you go live, in the live section.

Automatic retry

If we encounter an error during a webhook request, we'll retry it up to 8 times. Additionally, outgoing webhook requests have a timeout of 15 seconds, after which the webhook event fails and an automatic retry is triggered.
The Swan webhook retry policy is exponential and behaves as follows:
Replay attempt
Time to trigger retry (estimated)
1
5 seconds
2
17 seconds
3
1 minute
4
3 minutes
5
15 minutes
6
40 minutes
7
2 hours
8
7 hours
If all retrys fail, you can retry it manually.
You can also select Retry from your Dashboard to trigger a webhook retry.

Event data sent

We send a POST request with the following body :
{
"eventType": "Transaction.Booked",
"eventId": "{{YOUR_EVENT_ID}}",
"eventDate": "2021-08-18T09:35:46.673Z",
"projectId": "{{YOUR_PROJECT_ID}}",
"resourceId": "{{YOUR_RESOURCE_ID}}"
}
This example is an event triggered by the creation of a new transaction with the id bosci_46976252125703bac107f4f8a4ca5b3d. Each event is described by two data: eventType which tells you what action was performed and on which resource type, and eventIdwhich is unique for this action. For security reasons, we do not provide further information on our request. For more information on the resource impacted by the event, you must query our API.
Every request we make to your endpoint must be answered with the HTTP 200 code. If we receive another code, we consider it an error and retry the call a few seconds later. We make a maximum of eight tries per request. After that, you can still replay the request manually if you need to.

Event types

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.
This list of triggers is not exhaustive because the events are based on Swan's resources. transaction.created is an event type that is triggered every time there is a new transaction on your project. This could be a card payment, an incoming Sepa Credit Transfer, a received Sepa direct debit, or even a new type of transaction that hasn't been developed yet.
Account.Closed
An account was closed
Account.Created
An onboarding was finalized
Account.Updated
An account attribute was changed
Account.Closing
An account is closing
AccountHolder.Created
An onboarding was finalized
AccountHolder.Updated
A Banking Verification Status was updated by our compliance dept.
AccountInvoice.Generated
A new invoice is generated and available for download
AccountMembership.Bound
A user was bound with the accountMembership
AccountMembership.Created
A new accountMembership was created
AccountMembership.Disabled
An accountMembership was disabled
AccountMembership.Resumed
A suspended accountMembership was resumed
AccountMembership.Suspended
An accountMembership was suspended
AccountMembership.Updated
An accountMembership was updated by an action
AccountStatement.Generated
An accountStatement was generated
CapitalDepositCaseEvent.Created
A CapitalDepositCase was created
CapitalDepositCaseEvent.Updated
A CapitalDepositCase was updated
Card.Created
A new virtual card was created
Card.Updated
A physical card was printed, a spending limit was updated ...
Consent.Canceled
A consent was canceled by the partner
Consent.Created
A consent was created for a sensitive operation
Consent.Expired
A consent expired without being refused or granted
Consent.Granted
The user accepted a sensitive operation
Consent.Refused
The user refused a sensitive operation
Consent.Started
A consentURL was opened
FundingLimitSettingsChangeRequest.Created
A funding limit settings change request was created
FundingLimitSettingsChangeRequest.Updated
A funding limit settings change request was updated
FundingSource.Created
A funding source was created
FundingSource.Updated
A funding source was updated
MerchantProfile.Created
A merchant profile was created
MerchantProfile.Updated
A merchant profile was updated
Onboarding.Created
A new onboarding was created either through the API or the no-code interface
Onboarding.Updated
An onboarding was either finalized, or changed because new data was added to it
ReceivedDirectDebitMandate.Created
A receivedDirecDebitMandate was created either through the API or automatically by Swan
ReceivedDirectDebitMandate.Updated
A receivedDirecDebitMandate was updated
StandingOrder.Canceled
A standing order was canceled
StandingOrder.Scheduled
A standing order was scheduled
Transaction.Booked
A transaction was completed and will appear on the account statement
Transaction.Canceled
An upcoming direct debit was canceled
Transaction.Deleted
A scheduled direct debit was deleted
Transaction.Pending
An outboing Sepa Credit Transfer was processed and is waiting for the next SEPA batch, a card authorisation was accepted ...
Transaction.Rejected
A transaction was rejected for compliance reasons
Transaction.Released
A card authorization was released
Transaction.Upcoming
A transaction was booked for a future date
User.Joined
A user joins your project
User.Updated
A user's information was updated (for example, their phone number)
In case you have a whitelisting to set on your infrastructure, you may need to add those following IPs on your side (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.
Webhook endpoints might occasionally receive the same event more than once. We advise you to handle duplicated events by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.
An example that we can mention is related to transactions. Our Webhooks are designed following the At least once scheme. This implies that for the same transactionID you might get more than one notification, unlike At most once where notification is only sent once. The fundamental difference is that with this latter scheme, in case the notification is sent but not received, no retry operation will be conducted. This can be caused by some technical issues in the overall process or if the network fails. In case this happens, we might not send you a webhook notification, which in our opinion, is not a good practice. Therefore, we have adopted the At least once scheme.

Order of events

The order in which some events are delivered is not guaranteed. Let's take an example of a regular card payment flow (authorisation - debit - release). This one would generate the following events:
  • Transaction.Pending
  • Transaction.Booked
  • Transaction.Released
When the authorisation is created, you get the first event. However, when the transaction switches to Booked , you can either get the event in the order shown above, or the other way round (Released then Booked).