Webhooks

Webhooks allow Firefly III to send real-time notifications to external services when certain events occur, enabling powerful integrations and automation.

Overview

Webhooks in Firefly III can notify external services about:

Transaction creation, updates, and deletion
Budget creation, updates, and deletion
Budget limit changes

Webhooks are sent as HTTP POST requests with JSON payloads to URLs you configure

Webhook triggers

Firefly III supports the following webhook triggers:

Transaction events

STORE_TRANSACTION: New transaction created
UPDATE_TRANSACTION: Transaction updated
DESTROY_TRANSACTION: Transaction deleted

Budget events

STORE_BUDGET: New budget created
UPDATE_BUDGET: Budget updated
DESTROY_BUDGET: Budget deleted
STORE_UPDATE_BUDGET_LIMIT: Budget limit changed

Creating webhooks

Via web interface

Navigate to webhooks

Go to Automation > Webhooks in the main menu

Create new webhook

Click Create new webhook

Configure webhook

Fill in the webhook details:

Title: Descriptive name for the webhook
Trigger: Select which events should trigger this webhook
URL: The endpoint that will receive the webhook POST requests
Active: Enable or disable the webhook
Delivery: Choose delivery method (JSON recommended)

Save webhook

Click Submit to create the webhook

Via API

curl -X POST "https://your-firefly.local/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Transaction Notifier",
    "trigger": "STORE_TRANSACTION",
    "url": "https://your-service.com/webhook",
    "active": true,
    "response": "RESPONSE",
    "delivery": "JSON"
  }'

Webhook payload

When a webhook is triggered, Firefly III sends a POST request with a JSON payload:

{
  "uuid": "unique-message-id",
  "user_id": 1,
  "trigger": "STORE_TRANSACTION",
  "url": "https://your-service.com/webhook",
  "version": "2.0",
  "content": {
    "id": "123",
    "type": "transactions",
    "attributes": {
      "created_at": "2024-01-01T00:00:00+00:00",
      "updated_at": "2024-01-01T00:00:00+00:00",
      "description": "Groceries",
      "type": "withdrawal",
      "amount": "50.00",
      "currency_code": "EUR"
    }
  }
}

Payload structure

uuid

string

Unique identifier for this webhook message

user_id

integer

ID of the user who triggered the event

trigger

string

The event type that triggered this webhook (e.g., “STORE_TRANSACTION”)

url

string

The webhook URL that received this message

version

string

Webhook payload version (currently “2.0”)

content

object

The actual data object (transaction, budget, etc.) that triggered the webhook

Webhook delivery

Firefly III handles webhook delivery with these features:

Delivery options

JSON
Response

Recommended: Sends the full object as JSON

Complete transaction/budget data
Easy to parse
Includes all relationships

Retry logic

Firefly III automatically retries failed webhook deliveries:

Immediate attempt: First delivery attempt
Retry 1: After 1 minute
Retry 2: After 5 minutes
Retry 3: After 15 minutes
Retry 4: After 1 hour

After 5 failed attempts, the webhook message is marked as failed and will not be retried

Webhook attempts

Each delivery attempt is logged with:

HTTP status code
Response body
Timestamp
Success/failure status

You can view attempt history in the webhook details page.

Security

HTTPS recommended

Always use HTTPS endpoints for webhooks to ensure data is encrypted in transit

Webhook verification

To verify webhooks are from your Firefly III instance:

Check source IP: Whitelist your Firefly III server’s IP
Use unique URLs: Generate random URLs for each webhook
Verify payload: Check the uuid and user_id match expectations

Consider implementing a shared secret or signature verification in your webhook receiver for additional security

Testing webhooks

Before deploying webhooks to production:

Test with webhook.site

Generate test URL

Visit webhook.site and copy the unique URL

Create test webhook

Create a webhook in Firefly III using the webhook.site URL

Trigger event

Create a test transaction or budget

Verify payload

Check webhook.site to see the received payload

Manual trigger via API

You can manually trigger a webhook for testing:

curl -X POST "https://your-firefly.local/api/v1/webhooks/{id}/trigger" \
  -H "Authorization: Bearer YOUR_TOKEN"

Managing webhooks

Viewing webhook messages

To see all webhook messages and their delivery status:

Go to Automation > Webhooks
Click on a webhook to view its details
Navigate to the Messages tab

Here you can see:

All triggered events
Delivery status
Response codes
Attempt history

Disabling webhooks

To temporarily disable a webhook without deleting it:

Edit the webhook
Uncheck Active
Save changes

Disabled webhooks will not send any messages but their configuration is preserved

Deleting webhooks

Deleting a webhook also deletes all associated messages and attempt logs

Use cases

Slack notifications

Send Slack messages when large transactions are created:

Create a Slack incoming webhook
Create a Firefly III webhook with STORE_TRANSACTION trigger
Use a middleware service to format and forward to Slack

Budget alerts

Get notified when budgets are exceeded:

Set up webhook for STORE_UPDATE_BUDGET_LIMIT
Have your service check if spending exceeds limit
Send alert via email/SMS/push notification

External analytics

Send transaction data to analytics platforms:

Create webhook for all transaction events
Forward data to your analytics service
Build custom dashboards and insights

Automated workflows

Trigger external automations:

Use webhooks to notify workflow engines (Zapier, n8n, etc.)
Create complex multi-step automations
Integrate with other financial services

Troubleshooting

Webhooks not firing

Problem: Webhook events are not being sentSolutions:

Check webhook is Active
Verify trigger matches the event type
Check Firefly III logs for errors
Ensure URL is accessible from your server

Failed deliveries

Problem: Webhooks failing to deliverSolutions:

Check target URL is correct and accessible
Verify receiving server is responding with 2xx status codes
Check for SSL/TLS certificate issues
Review firewall rules

Missing data in payload

Problem: Webhook payload doesn’t include expected dataSolutions:

Ensure you’re using JSON delivery for full data
Check API version compatibility
Verify the object type matches webhook trigger

API reference

For complete webhook API documentation, see:

Webhooks API - Full CRUD operations
Webhook Messages - View message history
Manual Triggers - Test webhooks

Rules

Automate actions within Firefly III

API

Integrate with external services

Recurring transactions

Automate transaction creation

Automation

Overview of all automation features

Get Started

Installation

Core Features

Advanced

Administration

Overview

Webhook triggers

Transaction events

Budget events

Creating webhooks

Via web interface

Via API

Webhook payload

Payload structure

Webhook delivery

Delivery options

Retry logic

Webhook attempts

Security

HTTPS recommended

Webhook verification

Testing webhooks

Test with webhook.site

Manual trigger via API

Managing webhooks

Viewing webhook messages

Disabling webhooks

Deleting webhooks

Use cases

Troubleshooting

API reference

Rules

API

Recurring transactions

Automation

Build docs developers (and LLMs) love

Get Started

Installation

Core Features

Advanced

Administration

​Overview

​Webhook triggers

Transaction events

Budget events

​Creating webhooks

​Via web interface

​Via API

​Webhook payload

​Payload structure

​Webhook delivery

​Delivery options

​Retry logic

​Webhook attempts

​Security

​HTTPS recommended

​Webhook verification

​Testing webhooks

​Test with webhook.site

​Manual trigger via API

​Managing webhooks

​Viewing webhook messages

​Disabling webhooks

​Deleting webhooks

​Use cases

​Troubleshooting

​API reference

​Related features

Rules

API

Recurring transactions

Automation

Build docs developers (and LLMs) love

Overview

Webhook triggers

Creating webhooks

Via web interface

Via API

Webhook payload

Payload structure

Webhook delivery

Delivery options

Retry logic

Webhook attempts

Security

HTTPS recommended

Webhook verification

Testing webhooks

Test with webhook.site

Manual trigger via API

Managing webhooks

Viewing webhook messages

Disabling webhooks

Deleting webhooks

Use cases

Troubleshooting

API reference

Related features