Skip to content

Eventhooks

Igor Ramadas edited this page Dec 3, 2019 · 18 revisions

Using eventhooks you can automate payments and actions based on rules. For example, make transfer from one bunq account to another when specific payments are made. Or send a push notification when you get paid by someone. Or whatever you have in mind :-)

The concept is quite simple: you listen to events triggered on Jarbunq, and execute actions based on event / data filters.

Sample eventhooks definition

{
    "eventhooks": {
        "Bunq.callback": [
        {
            "data": {
                "eventType": "mutation_received",
                "accountName": "Main Account",
                "description": "salary"
            },
            "actions": [{
                "balanceTransfer": {
                    "toAlias": "my-savings-account@myemail.com",
                    "description": "Remaining balance auto saving",
                    "amount": 0.9
                },
                "push": {
                    "subject": "Monthly auto savings",
                    "message": "Salary received: ${amount}, 90% of current balance auto saved to savings account."
                }
            }]
        },
        {
            "data": {
                "eventType": "mutation_created",
                "amount": [">=", 1000]
            },
            "actions": [{
                "payment": {
                    "fromAlias": "my-main-account@myemail.com",
                    "toAlias": "my-savings-account@myemail.com",
                    "description": "High spending auto saving",
                    "amount": "10"
                },
                "email": {
                    "subject": "Large payment made: ${amount}",
                    "message": "A payment of ${amount} ${currency} was made to ${counterparty}. Auto saved 10 EUR to savings account."
                }
            }]
        }],
        "Strava.refreshToken": {
            "actions": {
                "url": "https://my-home-automation/strava-is-working"
            }
        }
    }
}

On the sample above:

  • Bunq.callback: when you receive a payment containing "salary" on your "Main Account", transfer 90% of the remaining balance to your savings account, and send a push notification confirming that salary was received.
  • Bunq.callback: each payment created with the amount of 1000 EUR or higher, will trigger an automated payment of 10 EUR from your main acount to the savings account, and send an email to the user with subject "Large payent made" and a summary of the payment as the message body.
  • Strava.refreshToken: each time a new token is fetched from Strava, it will post the full token detais to the URL "https://my-home-automation/strava-is-working".

Defining eventhooks

Each eventhook must contain 2 properties: data and actions.

data

Data filters, contains key / pairs to filter specific event data. The filter value can be either a primitive value (string, number, boolean...) or an array with 2 indexes: first the condition, and second the actual value. If you set as a primitive value, then it will assume the default has condition and compare it as string.

Conditions

  • has Must contain the specified value
  • eq Equals to, can also be set as "="
  • neq Not equals to, can also be set as "!="
  • lt Less than, can also be set as "<"
  • lte Less than or equal, can also be set as "<="
  • gt Greater than, can also be set as ">"
  • gte Greater than or equal, can also be set as ">="

Please note that has will do a case insensitive match, while eq and neq are case sensitive. This is important as some fields from bunq might come uppercased (callback event type, for example).

actions

Object or array of objects defining the actions to be executed. Each action has its own set of properties, which are detailed further down this page. You can also pass values from the event data to the action, by prefixing the field name with a double @@. And to pass the full object from the event to the action, simply set a field to @@. You can also use TypeScript style string templates, using ${property} tags to be replaced with values from the event's data.

Available actions:

  • payment Make a payment from a bunq account to any other account
  • balanceTransfer Transfer balance from one account to another
  • email Send an email
  • push Send a push notification
  • url Make a REST call (webhook)

Some examples for a payment notification (callback) received from bunq:

{
    "actions": {
        "payment": {
            "amount": "@@amount",
            "description": "@@description"
        },
        "balanceTransfer": {
            "fromAlias": "my-main-account@myemail.com",
            "toAlias": "my-other-account@myemail.com",
            "amount": 0.65
        },
        "url": {
            "uri": "https://some.endpoint.com/hello",
            "body": "@@"
        },
        "email": {
            "subject": "Callback from bunq",
            "message": "Payment of ${amount}: ${description}"
        },
        "push": {
            "subject": "${amount} ${currency} received",
            "message": "@@"
        }
    }
}

Actions

payment

Makes a payment to the specified counterparty. To use this action in conjuction to Bunq.callbacks, you must define data filters for the incoming callbacks.

{
    "fromAlias": "string or number, source account, defaults to main account",
    "toAlias": "string or number, target account",
    "toName": "string, mandatory if sending to IBAN",
    "description": "string",
    "amount": "number",
    "currency": "string, defaults to EUR",
    "draft": "boolean, defaults to value of global settings",
    "notes": "string or string[]"
}

List of all available options at https://jarbunq.devv.com/interfaces/_types_.paymentoptions.html

balanceTransfer

Transfer a percentage of the balance from one bunq account to another. It expects the same options as payment above, with the important difference that the amount represents the percentage (in decimal) of the balance to be transferred, from 0.001 (0.1%) to 1 (100%).

{
    "fromAlias": "string or number, source account, defaults to main account",
    "toAlias": "string or number, target account",
    "toName": "string, mandatory if sending to IBAN",
    "description": "string",
    "amount": "number, from 0.001 to 1",
    "currency": "string, defaults to EUR",
    "draft": "boolean, defaults to value of global settings",
    "notes": "string or string[]"
}

Please note that the balanceTransfer behaviour depends on the event being triggered. When coupled with a Bunq.callback event, it will get the account balance right before the balance mutation (using the payment / mutation / balance values from the callback itself). For all other events, it will query the current balance of the account in real time.

url

Calls the specified URL. If you define it as a simple string, it will POST the data passed on the event to the specified URL. Or you can set the full options, according to the request module.

{
    "uri": "string, full URL to the endpoint including https://",
    "method": "defaults to POST",
    "json": "boolean, defaults to true"
}

List of all available options at https://www.npmjs.com/package/request#requestoptions-callback

email

Sends an email.

{
    "subject": "string",
    "message": "string",
    "from": "string, defaults to user's email",
    "to": "string, target email"
}

List of all available options at https://jarbunq.devv.com/interfaces/_types_.emailnotificationoptions.html

push

Sends a push notification.

{
    "subject": "string",
    "message": "string"
}

List of all available options at https://jarbunq.devv.com/interfaces/_types_.pushnotificationoptions.html

Events

Below you'll find a list of events triggered by Jarbunq that you can listen to and trigger actions.

Bunq.callback

When Jarbunq receives a notification from bunq, mostly for payments and card transactions. Expects a BunqCallback object.

{
    "type": "string, for instance PAYMENT",
    "eventType": "string, for instance MUTATION_RECEIVED or MUTATION_CREATED",
    "description": "string",
    "dateCreated": "date",
    "dateUpdated": "date, usually right after the dateCreated",
    "counterparty": "string, name or IBAN",
    "amount": "number",
    "currency": "string",
    "originalAmount": "number",
    "originalCurrency": "string",
    "feeAmount": "number",
    "feeCurrency": "string",
    "accountId": "number, the monetary account ID",
    "cardId": "number, the user card ID (not the credit card number!)",
    "cardType": "string, type of card (MAESTRO, MASTERCARD, MASTERCARD_VIRTUAL etc)",
    "cardLabel": "string, label or description assigned to the card",
    "status": "string, payment / clearing status",
    "location": "string, city or location details"
}

Bunq.makePayment

When Jarbunq makes a payment. Expects a PaymentOptions object.

{
    "fromAlias": "string or number, source account, defaults to main account",
    "toAlias": "string or number, target account",
    "toName": "string, mandatory if sending to IBAN",
    "description": "string",
    "amount": "number",
    "currency": "string, defaults to EUR",
    "draft": "boolean, defaults to value of global settings",
    "notes": "string or string[]"
}

Bunq.getAccounts

When Jarbunq refreshes the list of user accounts.

Bunq.setupCallbacks

When Jarbunq registers the callback URLs (notification filters) at bunq.

Notifications.send

When a notification is sent from Jarbunq to the user. Please note that this is a wrapper for email and push notifications, sending to one or another depending on settings. So it will also trigger a toEmail or toPush.

Notifications.toEmail

When an email is sent from Jarbunq to the user. Expects an EmailNotificationOptions object.

Notifications.toPush

When a push notification is sent from Jarbunq to the user. Expects a PushNotificationOptions object.

EmailAccount.start

When a registered email account starts up.

EmailAccount.stop

When a registered email account stops.

EmailAccount.processEmail

When new, relevant email arrives on a registered account.

EmailManager.start

When the Email Manager starts up.

EmailManager.stop

When the Email Manager stops.

EmailManager.sendWeeklyReport

When the weekly report email is sent to the user.

Strava.refreshToken

When Strava access tokens are refreshed.

Strava.payForActivities

When a payment is made for Strava activities. Expects a StravaPayment object.

Avoiding cascading events

Consider the following eventhook example to trigger a payment:

{
    "eventhooks": {
        "Bunq.callback": {
            "data": {
                "eventType": "payment_received",
                "description": "Rent"
            },
            "actions": {
                "payment": {
                    "toAlias": "my-rent-alias@email.com",
                    "description": "@@description",
                    "amount": "@@amount"
                }
            }
        }
    }
}

On the sample above, all payments to any of your accounts with the description containing "Rent" will trigger another payment to your "my-rent-alias@email.com" account, passing the same amount and description. But this will retrigger the event, as we're passing the same description received on the original payment.

Jarbunq has some safety measures in place to avoid duplicate payments by default, but depending on how you have crafted your eventhooks these payments might not be identified as duplicate, and this could cause troubles. On the sample above, it would retrigger the payment only once, and then it would fail with a duplicate payment message, but you would still have 1 undesired payment. To fix this, you could add more fields on the data filter, for instance "accountId" = 0123445.

Another common sample of (not really cascading) duplicates is regarding payment notifications. If you have notification.events.paymentSuccess set to true, you'll get push notifications for all sucessful payments made via Jarbunq. So if you have an eventhook with a push action, you'll end up receiving 2 notifications for the same payment, even thou their contents might be different.

To sum up, you must be careful when setting up eventhooks filters to avoid cascading / looping events.

Additional samples

Some more ideas and working examples:

Transfer from bike savings when purchase description has "bike"**

{
    "eventhooks": {
        "Bunq.callback": [
        {
            "data": {
                "eventType": "mutation_created",
                "accountName": "Main Account",
                "description": "bike"
            },
            "actions": [{
                "balanceTransfer": {
                    "fromAlias": "my-bike-account@myemail.com",
                    "toAlias": "my-main-account@myemail.com",
                    "description": "@@description",
                    "amount": "@@amount"
                }
            }]
        }]
    }
}

Donation of 5 EUR for every flight ticket purchased

{
    "eventhooks": {
        "Bunq.callback": [
        {
            "data": {
                "eventType": "mutation_created",
                "description": ["has", "easyjet", "ryanair", "lufthansa"]
            },
            "actions": [{
                "payment": {
                    "toAlias": "SOME-TREE-PLANTING-ORG-IBAN",
                    "description": "Donation 123456",
                    "amount": 5
                }
            }]
        }]
    }
}

Notify Strava related payments to friend by email

{
    "eventhooks": {
        "Strava.payForActivities": [
        {
            "actions": [{
                "email": {
                    "to": "my@friend.com",
                    "subject": "My weekly Strava savings",
                    "message": "@@"
                }
            }]
        }]
    }
}
You can’t perform that action at this time.