Skip to content

Commit f7d0bc2

Browse files
JC5JC5
committed
Add documentation for webhooks.
1 parent f247765 commit f7d0bc2

File tree

6 files changed

+248
-0
lines changed

6 files changed

+248
-0
lines changed

‎config.php

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,5 +33,6 @@
3333
'tags' => 'Manage all the user\'s tags.',
3434
'transactions' => 'Manage all the user\'s transactions.',
3535
'users' => 'Manage the users registered within Firefly III.',
36+
'webhooks' => 'Manage the user\'s webhooks.',
3637
];
3738

‎yaml/paths/webhooks.yaml

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
/api/v1/webhooks:
2+
get:
3+
summary: List all webhooks.
4+
description: List all the user's webhooks.
5+
operationId: listWebhook
6+
tags:
7+
- webhooks
8+
parameters:
9+
- in: query
10+
name: page
11+
description: The page number, if necessary. The default pagination is 50, so 50 webhooks per page.
12+
required: false
13+
schema:
14+
type: integer
15+
example: 1
16+
responses:
17+
'200':
18+
description: A list of webhooks.
19+
content:
20+
application/json:
21+
schema:
22+
$ref: '#/components/schemas/WebhookArray'
23+
post:
24+
summary: Store a new webhook
25+
description: |
26+
Creates a new webhook. The data required can be submitted as a JSON body or as a list of parameters. The webhook will be given a random secret.
27+
operationId: storeUser
28+
tags:
29+
- webhooks
30+
requestBody:
31+
content:
32+
application/json:
33+
schema:
34+
$ref: '#/components/schemas/Webhook'
35+
application/x-www-form-urlencoded:
36+
schema:
37+
$ref: '#/components/schemas/Webhook'
38+
description: "JSON array or key=value pairs with the necessary webhook information. See the model for the exact specifications."
39+
required: true
40+
responses:
41+
'200':
42+
description: 'New webhook stored, result in response.'
43+
content:
44+
application/json:
45+
schema:
46+
$ref: '#/components/schemas/WebhookSingle'
47+
'422':
48+
description: 'Validation errors (see body)'
49+
content:
50+
application/json:
51+
schema:
52+
$ref: '#/components/schemas/ValidationError'
53+
/api/v1/webhooks/{id}:
54+
get:
55+
summary: Get a single webhook.
56+
description: Gets all info of a single webhook.
57+
operationId: getWebhook
58+
parameters:
59+
- in: path
60+
name: id
61+
required: true
62+
schema:
63+
type: integer
64+
example: 1
65+
description: The webhook ID.
66+
tags:
67+
- webhooks
68+
responses:
69+
'200':
70+
description: 'The requested webhook.'
71+
content:
72+
application/json:
73+
schema:
74+
$ref: '#/components/schemas/WebhookSingle'
75+
'404':
76+
description: Webhook not found.
77+
put:
78+
operationId: updateWebhook
79+
tags:
80+
- webhooks
81+
description: Update existing webhook.
82+
summary: Update an existing webhook's information.
83+
parameters:
84+
- in: path
85+
name: id
86+
required: true
87+
schema:
88+
type: integer
89+
example: 1
90+
description: The webhook ID.
91+
requestBody:
92+
content:
93+
application/json:
94+
schema:
95+
$ref: '#/components/schemas/Webhook'
96+
application/x-www-form-urlencoded:
97+
schema:
98+
$ref: '#/components/schemas/Webhook'
99+
description: JSON array with updated webhook information. See the model for the exact specifications.
100+
required: true
101+
responses:
102+
'200':
103+
description: 'Updated webhook stored, result in response'
104+
content:
105+
application/json:
106+
schema:
107+
$ref: '#/components/schemas/WebhookSingle'
108+
'422':
109+
description: 'Validation errors (see body)'
110+
content:
111+
application/json:
112+
schema:
113+
$ref: '#/components/schemas/ValidationError'
114+
delete:
115+
operationId: deleteWebhook
116+
description: Delete a webhook.
117+
summary: Delete a webhook.
118+
tags:
119+
- webhooks
120+
parameters:
121+
- in: path
122+
name: id
123+
required: true
124+
schema:
125+
type: integer
126+
example: 1
127+
description: The webhook ID.
128+
responses:
129+
'204':
130+
description: Webhook deleted.
131+
'404':
132+
description: No such webhook.
133+
'500':
134+
description: Error when deleting.

‎yaml/schemas/Webhook.yaml

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Webhook:
2+
title: A single webhook
3+
type: object
4+
required:
5+
- title
6+
- trigger
7+
- response
8+
- delivery
9+
- url
10+
properties:
11+
created_at:
12+
type: string
13+
format: date-time
14+
example: "2018-09-17T12:46:47+01:00"
15+
readOnly: true
16+
updated_at:
17+
type: string
18+
format: date-time
19+
example: "2018-09-17T12:46:47+01:00"
20+
readOnly: true
21+
active:
22+
type: boolean
23+
format: boolean
24+
example: false
25+
description: Boolean to indicate if the webhook is active
26+
title:
27+
type: string
28+
format: string
29+
example: "Update magic mirror on new transaction"
30+
description: A title for the webhook for easy recognition.
31+
secret:
32+
type: string
33+
format: string
34+
example: "iMLZLtLx2JHWhK9Dtyuoqyir"
35+
readOnly: true
36+
description: A 24-character secret for the webhook. It's generated by Firefly III when saving a new webhook.
37+
trigger:
38+
type: string
39+
format: string
40+
nullable: false
41+
example: "TRIGGER_DESTROY_TRANSACTION"
42+
description: The trigger for the webhook.
43+
enum:
44+
- TRIGGER_STORE_TRANSACTION
45+
- TRIGGER_UPDATE_TRANSACTION
46+
- TRIGGER_DESTROY_TRANSACTION
47+
response:
48+
type: string
49+
format: string
50+
nullable: false
51+
example: "RESPONSE_TRANSACTIONS"
52+
description: Indicator for what Firefly III will deliver to the webhook URL.
53+
enum:
54+
- RESPONSE_TRANSACTIONS
55+
- RESPONSE_ACCOUNTS
56+
- RESPONSE_NONE
57+
delivery:
58+
type: string
59+
format: string
60+
nullable: false
61+
example: "DELIVERY_JSON"
62+
description: Format of the delivered response.
63+
enum:
64+
- DELIVERY_JSON
65+
url:
66+
type: string
67+
format: string
68+
example: "https://example.com"
69+
readOnly: false
70+
description: The URL of the webhook. Has to start with `https`.

‎yaml/schemas/WebhookArray.yaml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
WebhookArray:
2+
type: object
3+
required:
4+
- data
5+
- meta
6+
- links
7+
properties:
8+
data:
9+
type: array
10+
items:
11+
$ref: '#/components/schemas/WebhookRead'
12+
meta:
13+
$ref: '#/components/schemas/Meta'
14+
links:
15+
$ref: '#/components/schemas/PageLink'

‎yaml/schemas/WebhookRead.yaml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
WebhookRead:
2+
type: object
3+
required:
4+
- type
5+
- id
6+
- attributes
7+
- links
8+
properties:
9+
type:
10+
type: string
11+
format: string
12+
example: "webhooks"
13+
description: "Immutable value"
14+
id:
15+
type: integer
16+
format: int32
17+
example: 2
18+
attributes:
19+
$ref: '#/components/schemas/Webhook'
20+
links:
21+
$ref: '#/components/schemas/ObjectLink'

‎yaml/schemas/WebhookSingle.yaml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
WebhookSingle:
2+
type: object
3+
required:
4+
- data
5+
properties:
6+
data:
7+
$ref: '#/components/schemas/WebhookRead'

0 commit comments

Comments
 (0)