Webhooks

Get all the failed attempts of a single webhook message.

GET

https://firefly.example.com/api/v1/webhooks/{id}/messages/{messageId}/attempts

When a webhook message fails to send it will store the failure in an "attempt". You can view and analyse these. Webhook messages that receive too many attempts (failures) will not be sent again. You must first clear out old attempts before the message can go out again.

curl -X GET 'https://firefly.example.com/api/v1/webhooks/123/messages/1/attempts' \
  -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/123/messages/1/attempts', {
  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/123/messages/1/attempts',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "data": [
    {
      "type": "webhook_attempts",
      "id": "2",
      "attributes": {
        "created_at": "2026-10-01T00:00:00+00:00",
        "updated_at": "2026-10-01T00:00:00+00:00",
        "webhook_message_id": "5",
        "status_code": 404,
        "logs": "Page not found",
        "response": "Page not found"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 20,
      "per_page": 100,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

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

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

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

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

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

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.

idstringrequiredpath

The webhook ID.

messageIdintegerrequiredpath

The webhook message ID.

Response

200OKWebhookAttemptArray

A list of webhook attempts.

Response fields application/vnd.api+json

dataArray<WebhookAttemptRead>required

Show child attributes

typestringrequired

Immutable value

Example

webhook_attempts

idstringrequired

Example

attributesWebhookAttemptrequired

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

webhook_message_idstring

The ID of the webhook message this attempt belongs to.

Example

status_codeinteger<int32> | null

The HTTP status code of the error, if any.

Example

logsstring | null

Internal log for this attempt. May contain sensitive user data.

Example

Page not found

responsestring<amount> | null

Webhook receiver response for this attempt, if any. May contain sensitive user data.

Example

Page not found

metaMetarequired

Show child attributes

paginationobject

Show child attributes

totalinteger

Example

countinteger

Example

per_pageinteger

Example

current_pageinteger

Example

total_pagesinteger

Example

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.