Webhooks
Webhooks are used to communicate changes to a transaction or other entities within the Hurdlr API. If you subscribe to webhooks, then your server will be alerted every time an entity is modified or a notable lifecycle event occurs.
1. How it works
By subscribing to receive "ENTITY_UPDATE" webhooks, your server can asynchronously fetch updated data at the exact moment it becomes available. When that new data is available, the Hurdlr API will make a POST call to a URL of your choosing with the data needed for your server to update appropriately. This approach ensures your users always have up-to-date data while removing unnecessary polls/refreshes from your server, saving you valuable resources.
By subscribing to receive "LIFECYCLE_EVENT" webhooks, you can trigger timely lifecycle notifications (e.g. push notifications, emails, and/or other alerts) based on timely user actions. For example, if a user's client views their invoice, the Hurdlr API will make a POST call to a URL of your choosing with the data needed for your server to alert your user that their client viewed the invoice.
2. Subscribing to receive webhooks
Hurdlr's API team is here to help! Simply email [email protected] with the subject line "Subscribe to Webhooks", and provide the following info:
a. Your API client_Id
b. Webhook URL for the Sandbox environment
c. Webhook URL for the Production environment
Our API team will respond back within 5 business days and will fire off sample webhooks to your Sandbox Webhook URL, for your team to develop/test with.
3. ENTITY_UPDATE
An "ENTITY_UPDATE" webhook will contain a JSON body like the following:
{
"userId": "fake_userId",
"type": "ENTITY_UPDATE",
"entities": ["bankTransfer", "expense", "revenue", "taxPayment"]
}
The possible entities
and recommended actions on how to update each given entity are listed below:
Webhook Type | Entity | Recommended action |
---|---|---|
ENTITY_UPDATE | attachments | GET /attachments |
ENTITY_UPDATE | bankTransfer | GET /bankTransfers |
ENTITY_UPDATE | business | GET /businesses |
ENTITY_UPDATE | client | GET /clients |
ENTITY_UPDATE | expense | GET /expenses |
ENTITY_UPDATE | expenseCategory | GET /expenses/categories |
ENTITY_UPDATE | expenseRule | GET /expenses/rules |
ENTITY_UPDATE | glEntry | GET /glEntries |
ENTITY_UPDATE | invoice | GET /invoices |
ENTITY_UPDATE | invoiceSetup | GET /invoiceSetup |
ENTITY_UPDATE | personalExpenseCategory | GET /expenses/personalCategories |
ENTITY_UPDATE | revenue | GET /revenues |
ENTITY_UPDATE | revenueRule | GET /revenueRules |
ENTITY_UPDATE | taxPayment | GET /taxPayments |
ENTITY_UPDATE | userTaxSetup | GET /userTaxSetup |
4. LIFECYCLE_EVENT
A "LIFECYCLE_EVENT" webhook will contain a JSON body like the following:
{
"userId": "fake_userId",
"type": "LIFECYCLE_EVENT",
"event": "INVOICE_VIEWED",
"eventData": {
clientName: "Bill Tanner",
invoiceId: 21850,
invoiceName: "HUR-121"
}
}
Custom lifecycle events
The Hurdlr API team can customize events to power your ideal user experience. Don't hesitate to email us at [email protected] if you are looking for something that you don't see below.
Some of the possible events
and recommended messaging to notify your users are listed below:
Webhook Type | Event | Example message |
---|---|---|
LIFECYCLE_EVENT | BANK_ERROR | Re-link your Citi account |
LIFECYCLE_EVENT | BANK_LINKED | N/A (useful for triggering next set of onboarding steps/messages) |
LIFECYCLE_EVENT | EXPENSE_ADDED | 4 new expenses from *3333 need to be tagged. |
LIFECYCLE_EVENT | EXPENSE_TAGGED | 2 new expenses from *3333 were auto-tagged. |
LIFECYCLE_EVENT | INVOICE_PAID | Bill Tanner has paid Invoice HUR-121. |
LIFECYCLE_EVENT | INVOICE_PAYMENT_METHOD_STORED | Bill Tanner has added a card on file for future invoices. |
LIFECYCLE_EVENT | INVOICE_VIEWED | Bill Tanner has opened Invoice HUR-121. |
LIFECYCLE_EVENT | RECEIPT_ATTACHED | N/A (useful for triggering internal workflows) |
LIFECYCLE_EVENT | RECEIPT_EMAILED | A receipt email has been received and processed. |
LIFECYCLE_EVENT | REVENUE_ADDED | 3 new income transactions from *3332 need to be tagged. |
LIFECYCLE_EVENT | REVENUE_TAGGED | 1 new income transaction from *3332 was auto-tagged. |
Additional use cases
The above lifecycle events can be used in varying ways depending on your product's use case. For example, if your product manages corporate/employee spend, it may benefit your user experience to make the
EXPENSE_ADDED
event trigger a push notification prompting the user to add a receipt image. TheeventData
included with theEXPENSE_ADDED
event contains the information necessary to route the user to the exact transaction that requires a receipt.
Updated 6 months ago