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 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

Once a webhook is created you'll be able to get more information about its usage; you'll be able to 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. We also provide some global statistics about its usage like the number of hits on the URL and the error rate.

For security reasons, to go live with your webhooks, you have to manually configure them in the live section.

In the case we encounter an error on a webhook request, we allow you to replay it manually. With 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 :

{
"eventType": "Transaction.Booked",
"eventId": "513e7027-8320-42f1-bdb5-3ca630b9a4c6",
"eventDate": "2021-08-18T09:35:46.673Z",
"projectId": "ea0e5a52-63ab-4eb8-9645-eaf42357694f",
"resourceId": "bosci_46976252125703bac107f4f8a4ca5b3d"
}

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 gives 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 get another code, we consider it an error and retry the call a few seconds later. We try a maximum of three times for each 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

Example of triggers

Account.Created

Onboarding is finalized

Account.Updated

The account name is changed

AccountHolder.Created

Onboarding is finalized

AccountHolder.Updated

Banking Verification Status is updated by our compliance

AccountMembership.Bound

A user bound with the accountMembership

AccountMembership.Created

A new accountMembership is created

AccountMembership.Disabled

An accountMembership is disabled

AccountMembership.Resumed

A suspended accountMembership is resumed

AccountMembership.Suspended

An accountMembership is suspended

AccountMembership.Updated

An accountMembership is updated by an action

Card.Created

A new virtual card is created

Card.Updated

A physical card is printed, a spending limit is updated ...

Consent.Canceled

A consent is canceled by the partner

Consent.Created

A consent is 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 is opened

Transaction.Booked

A transaction is completed and will be on the account statement

Transaction.Canceled

An upcoming direct debit is canceled

Transaction.Deleted

A scheduled direct debit is deleted

Transaction.Pending

An outboing Sepa Credit Transfer is processed and is waiting for the next SEPA batch, a card authorisation is accepted ...

Transaction.Rejected

A transaction is rejected for compliance reasons

Transaction.Released

A card authorization is released

Transaction.Upcoming

A transaction is booked to be executed at a future date