Test a webhook endpoint

POST/v1/webhook-endpoints/{id}/test

Sends a signed test delivery to the endpoint and returns what happened.

Use it to check your URL and signature verification before real events arrive. The test is signed exactly like real deliveries and appears in the endpoint's delivery log. Nothing in your account changes.

Permission: integrations.manage
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: test_webhook_endpoint
CLI: freeinvoiceautomation webhook test
Available: At launch, 1 January 2027

test_webhook_endpoint

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/webhook-endpoints/<id>/test \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>'

{
  "data": {
    "id": "0193f363-4f5a-7b6c-8d7e-9f0a1b2c3d4e",
    "endpoint_id": "0193f360-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
    "event_id": "0193f361-2d3e-7f4a-8b5c-6d7e8f9a0b1c",
    "event_type": "document.paid",
    "payload": {
      "id": "0193f361-2d3e-7f4a-8b5c-6d7e8f9a0b1c",
      "type": "document.paid",
      "api_version": "v1",
      "created_at": "2027-01-21T14:05:00Z",
      "account_id": "0193f29d-0b1c-7d2e-8f3a-4b5c6d7e8f90",
      "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
      "data": {
        "object": {
          "id": "0193f2c4-9d8e-7f6a-8b5c-4d3e2f1a0b9c",
          "type": "invoice",
          "number": "INV-2027-0001",
          "status": "paid",
          "total_minor": "120000",
          "currency": "USD"
        }
      }
    },
    "status": "succeeded",
    "attempts": 1,
    "last_response_status": 200,
    "next_attempt_at": null,
    "delivered_at": "2027-01-07T10:05:01Z",
    "created_at": "2027-01-07T10:05:00Z"
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Headers

Idempotency-Keystring

Any unique string up to 255 characters. Required for API-key and MCP calls that create something; optional otherwise. See Idempotency.

Path Parameters

idstring<uuid>required

Id of the webhook endpoint.

Response

200 - application/json

idstring<uuid>

Id of the delivery.

endpoint_idstring<uuid>

The endpoint it was sent to.

event_idstring<uuid>

Id of the event. The same on every retry and redelivery, so receivers can ignore duplicates.

event_typestring

Event type, e.g. document.paid.

payloadobject

The JSON body that was sent.

statusenum<string>

failed is retried with exponential backoff; after the last attempt (about 24 hours) it becomes dead and can be redelivered by hand.

Available options: pending, succeeded, failed, dead

attemptsinteger

Attempts made so far.

last_response_statusinteger | null

HTTP status your endpoint returned last time.

next_attempt_atstring<date-time> | null

When the next retry is due.

delivered_atstring<date-time> | null

When your endpoint accepted it with a 2xx response.

created_atstring<date-time>

When the delivery was created.

Errors

connection_failed

not_found

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

Delete a webhook endpointPrevious List webhook deliveriesNext

test_webhook_endpoint

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/webhook-endpoints/<id>/test \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>'

{
  "data": {
    "id": "0193f363-4f5a-7b6c-8d7e-9f0a1b2c3d4e",
    "endpoint_id": "0193f360-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
    "event_id": "0193f361-2d3e-7f4a-8b5c-6d7e8f9a0b1c",
    "event_type": "document.paid",
    "payload": {
      "id": "0193f361-2d3e-7f4a-8b5c-6d7e8f9a0b1c",
      "type": "document.paid",
      "api_version": "v1",
      "created_at": "2027-01-21T14:05:00Z",
      "account_id": "0193f29d-0b1c-7d2e-8f3a-4b5c6d7e8f90",
      "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
      "data": {
        "object": {
          "id": "0193f2c4-9d8e-7f6a-8b5c-4d3e2f1a0b9c",
          "type": "invoice",
          "number": "INV-2027-0001",
          "status": "paid",
          "total_minor": "120000",
          "currency": "USD"
        }
      }
    },
    "status": "succeeded",
    "attempts": 1,
    "last_response_status": 200,
    "next_attempt_at": null,
    "delivered_at": "2027-01-07T10:05:01Z",
    "created_at": "2027-01-07T10:05:00Z"
  }
}