مرجع الواجهة البرمجية: Webhooks | وندرفاتورة للمطورين

مولَّد من مستند OpenAPI المنشور (الإصدار 1.4.0). https://fatoora.tw.sa/api/v1

openapi.json openapi.yaml

Signed HTTPS notifications of the company's events, the endpoints that receive them, and the events list for polling.

GET /events

List recent events

الصلاحية المطلوبة 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.

المعاملات

الحقل	النوع	الوصف
`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).

الردود

200 A page of events.
default An error. error.code says which.

GET /webhook-endpoints

List webhook endpoints

الصلاحية المطلوبة 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.

المعاملات

الحقل	النوع	الوصف
`limit`	integer · query	Page size.
`cursor`	string · query	`meta.pagination.next_cursor` of the previous page.
`status`	string: active, disabled · query

الردود

200 A page of endpoints. Secrets are never listed.
default An error. error.code says which.

POST /webhook-endpoints

Register a webhook endpoint

الصلاحية المطلوبة 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.

محتوى الطلب application/json

الحقل	النوع	الوصف
`url` مطلوب	string (uri)
`events` مطلوب	array<string>
`description`	string \| null

الردود

201 The endpoint, with its secret (shown this once).
default An error. error.code says which.

GET /webhook-endpoints/{endpoint}

Get a webhook endpoint

الصلاحية المطلوبة webhooks:manage

المعاملات

الحقل	النوع	الوصف
`endpoint` مطلوب	integer · path

الردود

200 The endpoint, without its secret.
default An error. error.code says which.

PATCH /webhook-endpoints/{endpoint}

Change a webhook endpoint

الصلاحية المطلوبة 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.

المعاملات

الحقل	النوع	الوصف
`endpoint` مطلوب	integer · path
`Idempotency-Key`	string · header	8 to 255 visible ASCII characters, unique per operation you mean to perform.

محتوى الطلب application/json

الحقل	النوع	الوصف
`url`	string (uri)
`events`	array<string>
`description`	string \| null
`status`	string: active, disabled

الردود

200 The endpoint.
default An error. error.code says which.

DELETE /webhook-endpoints/{endpoint}

Remove a webhook endpoint

الصلاحية المطلوبة webhooks:manage

Deliveries still waiting for it are dropped.

المعاملات

الحقل	النوع	الوصف
`endpoint` مطلوب	integer · path

الردود

200 Removed.
default An error. error.code says which.

POST /webhook-endpoints/{endpoint}/rotate-secret

Rotate an endpoint's signing secret

الصلاحية المطلوبة 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.

المعاملات

الحقل	النوع	الوصف
`endpoint` مطلوب	integer · path

الردود

200 The endpoint, with its new secret (shown this once).
default An error. error.code says which.

POST /webhook-endpoints/{endpoint}/test

Send a test event

الصلاحية المطلوبة webhooks:manage

Queues a ping event to this endpoint only; it is delivered within a minute, signed like any other.

المعاملات

الحقل	النوع	الوصف
`endpoint` مطلوب	integer · path
`Idempotency-Key`	string · header	8 to 255 visible ASCII characters, unique per operation you mean to perform.

الردود

202 The test delivery, queued.
default An error. error.code says which.

GET /webhook-endpoints/{endpoint}/deliveries

List an endpoint's deliveries

الصلاحية المطلوبة webhooks:manage

المعاملات

الحقل	النوع	الوصف
`endpoint` مطلوب	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

الردود

200 A page of deliveries, newest first.
default An error. error.code says which.

POST /webhook-deliveries/{delivery}/redeliver

Redeliver an event

الصلاحية المطلوبة webhooks:manage

Starts a new series of attempts for the same event, with the same event id.

المعاملات

الحقل	النوع	الوصف
`delivery` مطلوب	string · path
`Idempotency-Key`	string · header	8 to 255 visible ASCII characters, unique per operation you mean to perform.

الردود

202 The delivery, queued again.
default An error. error.code says which.

العودة إلى مرجع الواجهة البرمجية

جاهز للبدء؟

الوصول إلى الواجهة البرمجية ضمن باقات: الأعمال والمؤسسات. أنشئ مفتاحًا من الإعدادات ← مفاتيح API وأرسل أول طلب خلال دقائق.

احصل على مفتاح API البدء السريع تواصل معنا