Guide
API
Webhook
Introduction
With our GraphQL API you can request data and perform actions on your accounts, cards, transactions, etc. This is a communication process where you (or your user) asks 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 real-time rather than a few minutes or hours later.
How to get data using a webhook
Banking data is sensitive, that is why we require authentication to access it. Since Swan is all about making banking operations easy, we chose not to send any sensitive data through webhook requests. Therefore, if you want to access the data impacted by the 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 4 characteristics:
status: a webhook can be Enabled or Disabledlabel: input a short text of your choiceendpoint URL: the URL we will requestevents: the list of event types where we requestendpoint URL
Once a webhook is created, you'll be able to get more information about its usage; you can see all requests up to that point. This allows you to troubleshoot any errors you might encounter and to 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, when you go live, you'll have to manually configure your webhooks again in the live section.
If we encounter an error during a webhook request, we'll replay it up to 4 times. If all the tries fail, we'll then let you replay it manually. With just a click, you can catch the event you missed and synchronize your processes.
Event data sent
We send a POST request with the following body :
1
{
2
"eventType": "Transaction.Booked",
3
"eventId": "513e7027-8320-42f1-bdb5-3ca630b9a4c6",
4
"eventDate": "2021-08-18T09:35:46.673Z",
5
"projectId": "ea0e5a52-63ab-4eb8-9645-eaf42357694f",
6
"resourceId": "bosci_46976252125703bac107f4f8a4ca5b3d"
7
}
Copied!
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 three 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.EventType
Examples of triggers
Account.Created
An onboarding was finalized
Account.Updated
An account name was changed
AccountHolder.Created
An onboarding was finalized
AccountHolder.Updated
A Banking Verification Status was updated by our compliance dept.
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
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
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
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
Last modified 1mo ago
Export as PDF
Copy link