Webhooks API - Firefly III

Webhooks allow you to receive HTTP callbacks when specific events occur in Firefly III, enabling real-time integrations with external services.

Overview

Firefly III webhooks send POST requests to your specified URL when configured triggers fire. Common use cases include:

Sending notifications to messaging platforms (Slack, Discord)
Triggering automation workflows
Syncing data with external systems
Real-time monitoring and alerts

Webhooks must be enabled in your Firefly III configuration. Check the allow_webhooks setting in your environment.

Base Path

/api/v1/webhooks

Webhook Management

List All Webhooks

Retrieve all configured webhooks for your account.

curl -X GET "https://your-firefly-instance.com/api/v1/webhooks" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

page

integer

default:"1"

Page number for pagination

limit

integer

default:"50"

Number of webhooks per page

Get Single Webhook

Retrieve details of a specific webhook.

curl -X GET "https://your-firefly-instance.com/api/v1/webhooks/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Webhook

Create a new webhook configuration.

curl -X POST "https://your-firefly-instance.com/api/v1/webhooks" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "active": true,
    "title": "Transaction Notifications",
    "trigger": "STORE_TRANSACTION",
    "response": "TRANSACTIONS",
    "delivery": "JSON",
    "url": "https://your-service.com/webhook",
    "secret": "your-secret-key"
  }'

title

string

required

Descriptive name for the webhook

url

string

required

Destination URL to receive webhook POST requests

trigger

string

required

Event that triggers the webhook. Options: STORE_TRANSACTION, UPDATE_TRANSACTION, DESTROY_TRANSACTION

response

string

required

Type of data to send. Options: TRANSACTIONS, ACCOUNTS, NONE

delivery

string

required

Delivery format. Options: JSON, FORM

active

boolean

default:"true"

Whether the webhook is active

secret

string

Secret key for webhook signature validation

Update Webhook

Modify an existing webhook.

curl -X PUT "https://your-firefly-instance.com/api/v1/webhooks/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "title": "Disabled Webhook"
  }'

Delete Webhook

Remove a webhook configuration.

curl -X DELETE "https://your-firefly-instance.com/api/v1/webhooks/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Returns 204 No Content on success.

Webhook Triggers

Webhooks can be triggered by these transaction events:

STORE_TRANSACTION

Fired when a new transaction is created.

{
  "user_id": 1,
  "trigger": "STORE_TRANSACTION",
  "url": "https://your-firefly-instance.com/transactions/show/123",
  "version": "2.0.0",
  "content": {
    "id": "123",
    "type": "withdrawal",
    "amount": "50.00",
    "description": "Grocery shopping",
    "date": "2024-01-15",
    "source_name": "Checking Account",
    "destination_name": "Supermarket"
  }
}

UPDATE_TRANSACTION

Fired when an existing transaction is modified.

DESTROY_TRANSACTION

Fired when a transaction is deleted.

Manual Trigger

Manually trigger a webhook for testing or specific transaction.

Trigger Webhook for Transaction

curl -X POST "https://your-firefly-instance.com/api/v1/webhooks/1/trigger-transaction/123" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Returns 204 No Content and sends webhook message.

This endpoint is useful for testing webhook configurations without creating/modifying actual transactions.

Submit Webhook Messages

Force sending of pending webhook messages.

curl -X POST "https://your-firefly-instance.com/api/v1/webhooks/1/submit" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Webhook Messages

View the history of webhook deliveries.

List Webhook Messages

Get all messages sent for a webhook.

curl -X GET "https://your-firefly-instance.com/api/v1/webhooks/1/messages" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Single Message

curl -X GET "https://your-firefly-instance.com/api/v1/webhooks/1/messages/456" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Delete Message

curl -X DELETE "https://your-firefly-instance.com/api/v1/webhooks/1/messages/456" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Webhook Attempts

View delivery attempts for webhook messages (includes retries).

List Message Attempts

curl -X GET "https://your-firefly-instance.com/api/v1/webhooks/1/messages/456/attempts" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Single Attempt

curl -X GET "https://your-firefly-instance.com/api/v1/webhooks/1/messages/456/attempts/789" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Delete Attempt

curl -X DELETE "https://your-firefly-instance.com/api/v1/webhooks/1/messages/456/attempts/789" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Webhook Payload Format

JSON Delivery

When delivery is set to JSON, webhooks send:

{
  "user_id": 1,
  "trigger": "STORE_TRANSACTION",
  "url": "https://your-firefly-instance.com/transactions/show/123",
  "version": "2.0.0",
  "content": {
    "id": "123",
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "transactions": [
      {
        "transaction_journal_id": "456",
        "type": "withdrawal",
        "date": "2024-01-15T00:00:00+00:00",
        "amount": "50.00",
        "description": "Grocery shopping",
        "source_id": "1",
        "source_name": "Checking Account",
        "destination_id": "12",
        "destination_name": "Supermarket",
        "category_name": "Groceries",
        "budget_name": "Monthly Budget"
      }
    ]
  }
}

Form Delivery

When delivery is set to FORM, data is sent as application/x-www-form-urlencoded.

Security

Webhook Signatures

Use the secret field to validate webhook authenticity:

import hmac
import hashlib

def verify_webhook(secret, payload, signature):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Always validate webhook signatures to prevent unauthorized requests to your endpoint.

HTTPS Required

Webhook URLs should use HTTPS to protect data in transit.

Best Practices

Use HTTPS - Always configure webhook URLs with HTTPS
Validate signatures - Verify webhook authenticity using the secret
Respond quickly - Return 200 OK within 5 seconds to avoid retries
Handle idempotency - Process webhook messages idempotently
Monitor failures - Check webhook attempts for delivery issues
Test thoroughly - Use manual trigger endpoint for testing

Error Handling

Webhook Disabled

{
  "message": "Webhooks are not enabled."
}

Webhooks are disabled in the configuration. Enable with:

allow_webhooks=true

Invalid Configuration

{
  "message": "The given data was invalid.",
  "errors": {
    "url": ["The url must be a valid URL."]
  }
}

Retry Policy

Firefly III automatically retries failed webhook deliveries:

Failed requests (non-2xx status) are retried
View retry attempts in webhook attempts endpoint
Configure retry behavior in your Firefly III settings

Webhook endpoint documentation: https://api-docs.firefly-iii.org/?urls.primaryName=2.0.0%20(v1)#/webhooks

Use Cases

Slack Notifications

curl -X POST "https://your-firefly-instance.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Slack Transaction Alerts",
    "trigger": "STORE_TRANSACTION",
    "response": "TRANSACTIONS",
    "delivery": "JSON",
    "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
    "active": true
  }'

Discord Integration

curl -X POST "https://your-firefly-instance.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Discord Notifications",
    "trigger": "STORE_TRANSACTION",
    "response": "TRANSACTIONS",
    "delivery": "JSON",
    "url": "https://discord.com/api/webhooks/YOUR/WEBHOOK",
    "active": true
  }'

​Overview

​Base Path

​Webhook Management

​List All Webhooks

​Get Single Webhook

​Create Webhook

​Update Webhook

​Delete Webhook

​Webhook Triggers

​STORE_TRANSACTION

​UPDATE_TRANSACTION

​DESTROY_TRANSACTION

​Manual Trigger

​Trigger Webhook for Transaction

​Submit Webhook Messages

​Webhook Messages

​List Webhook Messages

​Get Single Message

​Delete Message

​Webhook Attempts

​List Message Attempts

​Get Single Attempt

​Delete Attempt

​Webhook Payload Format

​JSON Delivery

​Form Delivery

​Security

​Webhook Signatures

​HTTPS Required

​Best Practices

​Error Handling

​Webhook Disabled

​Invalid Configuration

​Retry Policy

​Use Cases

​Slack Notifications

​Discord Integration

​Next Steps

Data Operations

Search API

Overview

Base Path

Webhook Management

List All Webhooks

Get Single Webhook

Create Webhook

Update Webhook

Delete Webhook

Webhook Triggers

STORE_TRANSACTION

UPDATE_TRANSACTION

DESTROY_TRANSACTION

Manual Trigger

Trigger Webhook for Transaction

Submit Webhook Messages

Webhook Messages

List Webhook Messages

Get Single Message

Delete Message

Webhook Attempts

List Message Attempts

Get Single Attempt

Delete Attempt

Webhook Payload Format

JSON Delivery

Form Delivery

Security

Webhook Signatures

HTTPS Required

Best Practices

Error Handling

Webhook Disabled

Invalid Configuration

Retry Policy

Use Cases

Slack Notifications

Discord Integration

Next Steps