Event

Interacting with financial institutions via EBICS introduces a few problems due to the asynchronous nature of todays banking systems. Transactions are cleared once (or multiple times) a day via a central service. Due to this fact:

  • Failure and success can only be determined hours after the API request was made
  • Recurring transactions only have an initial API request, yet remote systems need to know their status

To solve those problems, the EBICS::Box tracks all important events and delivers webhooks to remote systems. A webhook is a simple HTTP Post request to a predefined URL. Each webhook contains most relevant information about an event, so that remote systems can perform most tasks whithout the need of an extra API request.

Setup

In order to use webhooks, you need to setup a webhook_url for each account you want to track. Moreover, you need your organization's webhook_token to verify that requests are really originating from your EBICS::Box.

Use cases

  • Mark orders as paid once money has been received
  • Notify accounting when recurring direct debits fail
  • Notify accounting if a recipient's bank account has been closed
  • Store transfers on your remote system
  • Update internal dashboards

Integration

When adding an endpoint to receive webhooks, please respond with a success http response code (something in the 2xx range). Anything else will be considered a failure and the box will retry token delivery. The Box will attempt to deliver each webhook up to 20 times with increasing time between each attempt.

What can you do with Event?

The EBICS::Box API lets you perform several different actions with an Account:

Event properties

id uuid

Unique id for every event. 

{ "id": "Customer payments" }
account string

IBAN of the account for which the event occured. 

{ "account": "DE12345678987654345678" }
type string

Type of event. 

{ "type": "credit_transfer_status_change" }
triggered_at datetime

Date and time when given event was triggered. 

{ "triggered_at": "2016-05-06 12:00:00" }
payload object

Actual event payload. This differs from event to event. A list of all event types and their corresponding payloads is provided later in this document. 

{ "payload": "depends on event" }
signature string

Based on your configuration key, the Box signs every webhook request. This way, you can ensure that payloads pushed to your webhook endpoint are really from the Box. Otherwise, "bad guys" might try to push fake webhooks to your publicly available webhook endpoint and trigger unwanted behaviour. 

{ "signature": "lkasdjfhuahwkljehfa83h3we89oh4298HOWPEIJASDP903IJAEODS" }
webhook_status string

Did the Box manage to deliver a webhook successfully. 

{ "webhook_status": "success" }
webhook_retries integer

How often did the Box try to deliver a webhook. 

{ "webhook_retries": 2 }
webhook_deliveries array of objects

List of all attempts to deliver a webhook to your remote system. This is not provided on list views, but only when fetching details for a single event. 

{
  "webhook_deliveries": [
    {
      "delivery_at": "2016-05-01 12:01:05",
      "response_body": "success",
      "response_status": 200,
      "response_time": 3
    },
    …
  ]
}
_links object

URLs for related resources and potential next actions 

{
  "_links": {
    "self": "https://…",
    "account": "https://…"
  }
}

Endpoints

GET /events
Fetch all events
page

Page to show

(default: 1)
per_page

Amount of results

(default: 10) (maximum: 100)

Fetch all events

GET /events

Response

HTTP/1.1 200 OK
[
  {
    "id": "30f83ad8-2291-11e6-b67b-9e71128cae77",
    "signature": "lkasdjfhuahwkljehfa83h3we89oh4298HOWPEIJASDP903IJAEODS",
    "account": "DE12345678987654345678",
    "type": "credit_transfer_status_change",
    "triggered_at": "2016-05-01 12:00:00",
    "webhook_status": "success",
    "webhook_retries": 2,
    "_links": {
      "self": "https://box.url/events/30f83ad8-2291-11e6-b67b-9e71128cae77"
    }
  },
  …
]
GET /events/:id
Fetch details for a single event
:id

ID of credit transfer you want to fetch

required

Fetch a single event

GET /events/30f83ad8-2291-11e6-b67b-9e71128cae77

Response

HTTP/1.1 200 OK
{
  "id": "30f83ad8-2291-11e6-b67b-9e71128cae77",
  "signature": "lkasdjfhuahwkljehfa83h3we89oh4298HOWPEIJASDP903IJAEODS",
  "account": "DE12345678987654345678",
  "type": "credit_transfer_status_change",
  "triggered_at": "2016-05-01 12:00:00",
  "payload": {
    … depending on event …
  },
  "webhook_status": "success",
  "webhook_retries": 2,
  "webhook_deliveries": [
    {
      "delivery_at": "2016-05-01 12:01:05",
      "response_body": "success",
      "response_status": 200,
      "response_time": 3
    },
    …
  ],
  "_links": {
    "self": "https://box.url/events/30f83ad8-2291-11e6-b67b-9e71128cae77"
  }
}