Getting notified with webhooks

EBICS is asynchronous in nature as many bank servers are still handle their order in large batches. Therefore, we cannot expect that credits and direct debits will be executed immediately. In order to keep things easy for developers, we use the common webhook pattern. Whenever something noteworthy happens, the box will notify a remote system about it. This could be failed or succeeded direct debits or newly fetched transactions. No need to pull data, we will push it to your app.

Before you get started, the box needs to know where to push those notifications (You can set basic auth data via http://user:password@host/).

    curl -XPUT /accounts/DE02700205000007808005 \
      -H 'Accept: ' \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer " \
      -d '{"callback_url": "https://your_app.url/callback"}'

Whenever you change the callback url, we will send a test notification to the url. A webhook for a new statement would look like this:

      "id": "3e977891-2785-4c2c-9d01-6e68eb2a3421",
      "account_id": 1,
      "statement": {
        "id": "3e977891-2785-4c2c-9d01-6e68eb2a3421",
        "account": "DE00000000000000000001",
        "name": "NAME",
        "bic": "YOURBIC",
        "iban": "DE00000000000000000002",
        "type": "debit",
        "amount": 1000,
        "date": "2017-01-01",
        "remittance_information": "XYZ SAGT DANKE",
        "eref": "some-eref",
        "mref": "some-mref",
        "reference": "NONREF",
        "bank_reference": "bank-ref",
        "creditor_identifier": "DExxxxxxxxxxxyz",
        "transaction_type": "NDDT",
        "_links": {
          "self": "https://box.url/DE00000000000000000001/statements/1",
          "account": "https://box.url/DE00000000000000000001/",
          "transaction": null
      "action": "statement_created",
      "triggered_at": "2016-06-20T09:50:36.946+02:00"