-
-
Notifications
You must be signed in to change notification settings - Fork 1
Eventhooks
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.
{
"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".
Each eventhook must contain 2 properties: data and actions.
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.
- 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).
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": "@@"
}
}
}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
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.
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
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
Sends a push notification.
{
"subject": "string",
"message": "string"
}List of all available options at https://jarbunq.devv.com/interfaces/_types_.pushnotificationoptions.html
Below you'll find a list of events triggered by Jarbunq that you can listen to and trigger actions.
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"
}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[]"
}When Jarbunq refreshes the list of user accounts.
When Jarbunq registers the callback URLs (notification filters) at bunq.
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.
When an email is sent from Jarbunq to the user. Expects an EmailNotificationOptions object.
When a push notification is sent from Jarbunq to the user. Expects a PushNotificationOptions object.
When a registered email account starts up.
When a registered email account stops.
When new, relevant email arrives on a registered account.
When the Email Manager starts up.
When the Email Manager stops.
When the weekly report email is sent to the user.
When Strava access tokens are refreshed.
When a payment is made for Strava activities. Expects a StravaPayment object.
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.
Some more ideas and working examples:
{
"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"
}
}]
}]
}
}{
"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
}
}]
}]
}
}{
"eventhooks": {
"Strava.payForActivities": [
{
"actions": [{
"email": {
"to": "my@friend.com",
"subject": "My weekly Strava savings",
"message": "@@"
}
}]
}]
}
}Need help? Open an issue
- Source code docs: https://jarbunq.devv.com
- bunq API docs: https://doc.bunq.com/