Webhooks

List all webhooks.

GET

https://firefly.example.com/api/v1/webhooks

List all the user's webhooks.

List all webhooks.

curl -X GET 'https://firefly.example.com/api/v1/webhooks' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/webhooks', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://firefly.example.com/api/v1/webhooks',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "data": [
    {
      "type": "webhooks",
      "id": "2",
      "attributes": {
        "created_at": "2026-10-01T00:00:00+00:00",
        "updated_at": "2026-10-01T00:00:00+00:00",
        "active": false,
        "title": "Update magic mirror on new transaction",
        "secret": "iMLZLtLx2JHWhK9Dtyuoqyir",
        "triggers": [
          "STORE_TRANSACTION",
          "UPDATE_TRANSACTION"
        ],
        "responses": [
          "TRANSACTIONS"
        ],
        "deliveries": [
          "JSON"
        ],
        "url": "https://example.com"
      },
      "links": {
        "0": {
          "rel": "self",
          "uri": "/OBJECTS/1"
        },
        "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 20,
      "per_page": 100,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "links": {
    "self": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=4",
    "first": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=1",
    "next": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=3",
    "prev": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=2",
    "last": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=12"
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Parameters

limitinteger<int32>query

Number of items per page. The default pagination is per 50 items.

pageinteger<int32>query

Page number. The default pagination is per 50 items.

Response

200OKWebhookArray

A list of webhooks.

Response fields application/vnd.api+json

dataArray<WebhookRead>required

Show child attributes

typestringrequired

Immutable value

Example

webhooks

idstringrequired

Example

attributesWebhookPropertiesrequired

Show child attributes

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

activeboolean

Boolean to indicate if the webhook is active

Example

false

titlestringrequired

A title for the webhook for easy recognition.

Example

Update magic mirror on new transaction

secretstringread only

A 24-character secret for the webhook. It's generated by Firefly III when saving a new webhook. If you submit a new secret through the PUT endpoint it will generate a new secret for the selected webhook, a new secret bearing no relation to whatever you just submitted.

Example

iMLZLtLx2JHWhK9Dtyuoqyir

triggersArray<WebhookTrigger>ANYSTORE_TRANSACTIONUPDATE_TRANSACTIONDESTROY_TRANSACTIONSTORE_BUDGETUPDATE_BUDGETDESTROY_BUDGETSTORE_UPDATE_BUDGET_LIMIT

Example

[
  "STORE_TRANSACTION",
  "UPDATE_TRANSACTION"
]

responsesArray<WebhookResponse>TRANSACTIONSACCOUNTSBUDGETRELEVANTNONE

Example

[
  "TRANSACTIONS"
]

deliveriesArray<WebhookDelivery>JSON

Example

[
  "JSON"
]

urlstringrequired

The URL of the webhook. Has to start with https.

Example

https://example.com

linksObjectLinkrequired

Show child attributes

0object

Show child attributes

relstring

Example

self

uristring

Example

/OBJECTS/1

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECTS/1

metaMetarequired

Show child attributes

paginationobject

Show child attributes

totalinteger

Example

countinteger

Example

per_pageinteger

Example

current_pageinteger

Example

total_pagesinteger

Example

linksPageLinkrequired

Show child attributes

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=4

firststring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=1

nextstring<uri> | null

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=3

prevstring<uri> | null

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=2

laststring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=12

400Bad RequestBadRequestResponse

Bad request

Response fields application/json

messagestring

Example

Bad Request

exceptionstring

Example

BadRequestHttpException

401UnauthorizedUnauthenticatedResponse

Unauthenticated

Response fields application/json

messagestring

Example

Unauthenticated

exceptionstring

Example

AuthenticationException

404Not FoundNotFoundResponse

Page not found

Response fields application/json

messagestring

Example

Resource not found

exceptionstring

Example

NotFoundHttpException

500Internal Server ErrorInternalExceptionResponse

Internal exception

Response fields application/json

messagestring

Example

Internal Exception

exceptionstring

Example

InternalException

Authorization

firefly_iii_authoauth2

OAuth2 authorization code flow. Create a client on your installation's /profile page; it authorizes at /oauth/authorize and issues tokens at /oauth/token there. The URLs below are the demo site's. How to use the API walks through it.

local_bearer_authhttp (bearer)

A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.