Generated from the published OpenAPI document (version 1.4.0). https://fatoora.tw.sa/api/v1
Signed HTTPS notifications of the company's events, the endpoints that receive them, and the events list for polling.
/events
List recent events
Requires scope
invoices:read
The company's events, newest first: the polling alternative to
webhooks, with the same data a delivery carries. Customer events
are listed only for a key that also holds customers:read. Events
are recorded while the company has an active webhook endpoint and
kept for 30 days.
Parameters
| Field | Type | Description |
|---|---|---|
limit
|
integer · query | Page size. |
cursor
|
string · query | meta.pagination.next_cursor of the previous page. |
type
|
array<string> · query | One or more event types (type[]=invoice.issued&type[]=invoice.paid, or comma-separated). |
Responses
- 200 A page of events.
-
default
An error.
error.codesays which.
/webhook-endpoints
List webhook endpoints
Requires scope
webhooks:manage
Needs the person behind the key to be allowed to manage the company's settings. An OAuth app sees only the endpoints it registered itself; an API key sees every endpoint of the company.
Parameters
| Field | Type | Description |
|---|---|---|
limit
|
integer · query | Page size. |
cursor
|
string · query | meta.pagination.next_cursor of the previous page. |
status
|
string: active, disabled · query |
Responses
- 200 A page of endpoints. Secrets are never listed.
-
default
An error.
error.codesays which.
/webhook-endpoints
Register a webhook endpoint
Requires scope
webhooks:manage
The URL must be a public https address on port 443 or 8443, with a
domain name (not an IP address) that resolves only to public
addresses; it is checked again before every delivery. The answer
carries the signing secret, once: store it now. At most 10
endpoints per company. No Idempotency-Key: a stored replay would
keep the secret.
events may only name types your credential can read
(invoices:read for invoice and note events, customers:read for
customer events); any other type answers 422 validation_failed,
and so does a credential that can read none. * is stored as
exactly the types your credential can read.
An endpoint an OAuth app registers belongs to that app's connection
to the company: it is switched off (disabled_reason
connection_revoked or connection_suspended) when the connection
is revoked or suspended, stays off after a new consent, and never
receives an event the connection's current scopes cannot read.
Request body application/json
| Field | Type | Description |
|---|---|---|
url
required
|
string (uri) | |
events
required
|
array<string> | |
description
|
string | null |
Responses
- 201 The endpoint, with its secret (shown this once).
-
default
An error.
error.codesays which.
/webhook-endpoints/{endpoint}
Get a webhook endpoint
Requires scope
webhooks:manage
Parameters
| Field | Type | Description |
|---|---|---|
endpoint
required
|
integer · path |
Responses
- 200 The endpoint, without its secret.
-
default
An error.
error.codesays which.
/webhook-endpoints/{endpoint}
Change a webhook endpoint
Requires scope
webhooks:manage
Only the fields sent change. status switches it off (disabled) or
on again (active, which also clears its failure count). New
events follow the same rule as on creation. A new url, or
switching on again, also needs your credential to read every type the
endpoint subscribes to. An app's endpoint cannot be switched on while
its connection is not active.
Parameters
| Field | Type | Description |
|---|---|---|
endpoint
required
|
integer · path | |
Idempotency-Key
|
string · header | 8 to 255 visible ASCII characters, unique per operation you mean to perform. |
Request body application/json
| Field | Type | Description |
|---|---|---|
url
|
string (uri) | |
events
|
array<string> | |
description
|
string | null | |
status
|
string: active, disabled |
Responses
- 200 The endpoint.
-
default
An error.
error.codesays which.
/webhook-endpoints/{endpoint}
Remove a webhook endpoint
Requires scope
webhooks:manage
Deliveries still waiting for it are dropped.
Parameters
| Field | Type | Description |
|---|---|---|
endpoint
required
|
integer · path |
Responses
- 200 Removed.
-
default
An error.
error.codesays which.
/webhook-endpoints/{endpoint}/rotate-secret
Rotate an endpoint's signing secret
Requires scope
webhooks:manage
Returns the new secret, once. For the next 24 hours deliveries carry
two signatures (a v1= with the new secret and a v1= with the
previous one), so the receiver can switch without missing any.
Parameters
| Field | Type | Description |
|---|---|---|
endpoint
required
|
integer · path |
Responses
- 200 The endpoint, with its new secret (shown this once).
-
default
An error.
error.codesays which.
/webhook-endpoints/{endpoint}/test
Send a test event
Requires scope
webhooks:manage
Queues a ping event to this endpoint only; it is delivered within a minute, signed like any other.
Parameters
| Field | Type | Description |
|---|---|---|
endpoint
required
|
integer · path | |
Idempotency-Key
|
string · header | 8 to 255 visible ASCII characters, unique per operation you mean to perform. |
Responses
- 202 The test delivery, queued.
-
default
An error.
error.codesays which.
/webhook-endpoints/{endpoint}/deliveries
List an endpoint's deliveries
Requires scope
webhooks:manage
Parameters
| Field | Type | Description |
|---|---|---|
endpoint
required
|
integer · path | |
limit
|
integer · query | Page size. |
cursor
|
string · query | meta.pagination.next_cursor of the previous page. |
status
|
string: pending, delivering, succeeded, failed, abandoned · query |
Responses
- 200 A page of deliveries, newest first.
-
default
An error.
error.codesays which.
/webhook-deliveries/{delivery}/redeliver
Redeliver an event
Requires scope
webhooks:manage
Starts a new series of attempts for the same event, with the same event id.
Parameters
| Field | Type | Description |
|---|---|---|
delivery
required
|
string · path | |
Idempotency-Key
|
string · header | 8 to 255 visible ASCII characters, unique per operation you mean to perform. |
Responses
- 202 The delivery, queued again.
-
default
An error.
error.codesays which.
Ready to build?
API access is part of the Business and Enterprise plans. Create a key in Settings → API keys and make your first call in minutes.