Skip to content

Commit f42c63a

Browse files
pwizlapwizla
committed
Reformat #2849 content
1 parent 24266ba commit f42c63a

File tree

3 files changed

+169
-158
lines changed

3 files changed

+169
-158
lines changed

‎docusaurus/docs/cms/backend-customization/webhooks.md‎

Lines changed: 85 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -68,30 +68,105 @@ export default {
6868
</TabItem>
6969
</Tabs>
7070

71-
## Securing your webhooks
71+
## Webhooks security
7272

7373
Most of the time, webhooks make requests to public URLs, therefore it is possible that someone may find that URL and send it wrong information.
7474

7575
To prevent this from happening you can send a header with an authentication token. Using the Admin panel you would have to do it for every webhook.
7676

77-
:::tip Verify signatures
78-
In addition to auth headers, sign webhook payloads and verify signatures server‑side to prevent tampering and replay attacks.
77+
78+
Another way is to define `defaultHeaders` to add to every webhook request.
79+
80+
You can configure these global headers by updating the file at `./config/server`:
81+
82+
<Tabs>
83+
84+
<TabItem value="simple-token" label="Simple token">
85+
86+
<Tabs groupId="js-ts">
87+
<TabItem value="js" label="JavaScript">
88+
89+
```js title="./config/server.js"
90+
module.exports = {
91+
webhooks: {
92+
defaultHeaders: {
93+
Authorization: "Bearer my-very-secured-token",
94+
},
95+
},
96+
};
97+
```
98+
99+
</TabItem>
100+
101+
<TabItem value="ts" label="TypeScript">
102+
103+
```js title="./config/server.ts"
104+
export default {
105+
webhooks: {
106+
defaultHeaders: {
107+
Authorization: "Bearer my-very-secured-token",
108+
},
109+
},
110+
};
111+
```
112+
113+
</TabItem>
114+
</Tabs>
115+
116+
</TabItem>
117+
118+
<TabItem value="environment-variable" label="Environment variable">
119+
120+
<Tabs groupId="js-ts">
121+
<TabItem value="js" label="JavaScript">
122+
123+
```js title="./config/server.js"
124+
module.exports = {
125+
webhooks: {
126+
defaultHeaders: {
127+
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
128+
},
129+
},
130+
};
131+
```
132+
133+
</TabItem>
134+
135+
<TabItem value="ts" label="TypeScript">
136+
137+
```js title="./config/server.ts"
138+
export default {
139+
webhooks: {
140+
defaultHeaders: {
141+
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
142+
},
143+
},
144+
};
145+
```
146+
147+
</TabItem>
148+
</Tabs>
149+
150+
</TabItem>
151+
152+
</Tabs>
153+
154+
If you are developing the webhook handler yourself you can now verify the token by reading the headers.
155+
156+
### Verifying signatures
157+
158+
In addition to auth headers, it's recommended to sign webhook payloads and verify signatures server‑side to prevent tampering and replay attacks. To do so, you can use the following guidelines:
79159

80160
- Generate a shared secret and store it in environment variables
81161
- Have the sender compute an HMAC (e.g., SHA‑256) over the raw request body plus a timestamp
82162
- Send the signature (and timestamp) in headers (e.g., `X‑Webhook‑Signature`, `X‑Webhook‑Timestamp`)
83163
- On receipt, recompute the HMAC and compare using a constant‑time check
84164
- Reject if the signature is invalid or the timestamp is too old to mitigate replay
85165

86-
Learn more:
87-
- <ExternalLink to="https://owasp.org/www-community/attacks/Replay_Attack" text="OWASP replay attacks" />,
88-
- <ExternalLink to="https://nodejs.org/api/crypto.html#class-hmac" text="Node.js HMAC" />.
89-
:::
90-
91166
<details>
92167
<summary>Example: Verify HMAC signatures (Node.js)</summary>
93168

94-
Here is a minimal Node.js middleware example (pseudo‑code) showing HMAC verification:
169+
Here is a minimal Node.js middleware example (pseudo‑code) showing <ExternalLink text="HMAC" to="https://nodejs.org/api/crypto.html#class-hmac" /> verification:
95170

96171
<Tabs groupId="js-ts">
97172
<TabItem value="js" label="JavaScript">
@@ -161,91 +236,12 @@ export default (config: unknown, { strapi }: any) => {
161236
</TabItem>
162237
</Tabs>
163238

164-
Additional external examples:
239+
Here a few additional external examples:
165240
- <ExternalLink to="https://docs.github.com/webhooks/using-webhooks/validating-webhook-deliveries" text="GitHub — Validating webhook deliveries" />
166241
- <ExternalLink to="https://stripe.com/docs/webhooks/signatures" text="Stripe — Verify webhook signatures" />
167242
<br />
168243
</details>
169244

170-
171-
Another way is to define `defaultHeaders` to add to every webhook request.
172-
173-
You can configure these global headers by updating the file at `./config/server`:
174-
175-
<Tabs>
176-
177-
<TabItem value="simple-token" label="Simple token">
178-
179-
<Tabs groupId="js-ts">
180-
<TabItem value="js" label="JavaScript">
181-
182-
```js title="./config/server.js"
183-
module.exports = {
184-
webhooks: {
185-
defaultHeaders: {
186-
Authorization: "Bearer my-very-secured-token",
187-
},
188-
},
189-
};
190-
```
191-
192-
</TabItem>
193-
194-
<TabItem value="ts" label="TypeScript">
195-
196-
```js title="./config/server.ts"
197-
export default {
198-
webhooks: {
199-
defaultHeaders: {
200-
Authorization: "Bearer my-very-secured-token",
201-
},
202-
},
203-
};
204-
```
205-
206-
</TabItem>
207-
</Tabs>
208-
209-
</TabItem>
210-
211-
<TabItem value="environment-variable" label="Environment variable">
212-
213-
<Tabs groupId="js-ts">
214-
<TabItem value="js" label="JavaScript">
215-
216-
```js title="./config/server.js"
217-
module.exports = {
218-
webhooks: {
219-
defaultHeaders: {
220-
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
221-
},
222-
},
223-
};
224-
```
225-
226-
</TabItem>
227-
228-
<TabItem value="ts" label="TypeScript">
229-
230-
```js title="./config/server.ts"
231-
export default {
232-
webhooks: {
233-
defaultHeaders: {
234-
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
235-
},
236-
},
237-
};
238-
```
239-
240-
</TabItem>
241-
</Tabs>
242-
243-
</TabItem>
244-
245-
</Tabs>
246-
247-
If you are developing the webhook handler yourself you can now verify the token by reading the headers.
248-
249245
<!--- ### Usage
250246
251247
To access the webhook configuration panel, go to `Settings` > `Webhooks`.

‎docusaurus/static/llms-code.txt‎

Lines changed: 60 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -14104,9 +14104,68 @@ export default {
1410414104

1410514105

1410614106
## Securing your webhooks
14107-
Description: Here is a minimal Node.js middleware example (pseudo‑code) showing HMAC verification:
14107+
Description: You can configure these global headers by updating the file at ./config/server:
1410814108
(Source: https://docs.strapi.io/cms/backend-customization/webhooks#securing-your-webhooks)
1410914109

14110+
Language: JavaScript
14111+
File path: ./config/server.js
14112+
14113+
```js
14114+
module.exports = {
14115+
webhooks: {
14116+
defaultHeaders: {
14117+
Authorization: "Bearer my-very-secured-token",
14118+
},
14119+
},
14120+
};
14121+
```
14122+
14123+
---
14124+
Language: TypeScript
14125+
File path: ./config/server.ts
14126+
14127+
```ts
14128+
export default {
14129+
webhooks: {
14130+
defaultHeaders: {
14131+
Authorization: "Bearer my-very-secured-token",
14132+
},
14133+
},
14134+
};
14135+
```
14136+
14137+
Language: JavaScript
14138+
File path: ./config/server.js
14139+
14140+
```js
14141+
module.exports = {
14142+
webhooks: {
14143+
defaultHeaders: {
14144+
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
14145+
},
14146+
},
14147+
};
14148+
```
14149+
14150+
---
14151+
Language: TypeScript
14152+
File path: ./config/server.ts
14153+
14154+
```ts
14155+
export default {
14156+
webhooks: {
14157+
defaultHeaders: {
14158+
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
14159+
},
14160+
},
14161+
};
14162+
```
14163+
14164+
14165+
## Verifying signatures
14166+
Description: Here is a minimal Node.js middleware example (pseudo‑code) showing verification:
14167+
(Source: https://docs.strapi.io/cms/backend-customization/webhooks#verifying-signatures)
14168+
1411014169
Language: JavaScript
1411114170
File path: /src/middlewares/verify-webhook.js
1411214171

@@ -14172,60 +14231,6 @@ export default (config: unknown, { strapi }: any) => {
1417214231
};
1417314232
```
1417414233

14175-
Language: JavaScript
14176-
File path: ./config/server.js
14177-
14178-
```js
14179-
module.exports = {
14180-
webhooks: {
14181-
defaultHeaders: {
14182-
Authorization: "Bearer my-very-secured-token",
14183-
},
14184-
},
14185-
};
14186-
```
14187-
14188-
---
14189-
Language: TypeScript
14190-
File path: ./config/server.ts
14191-
14192-
```ts
14193-
export default {
14194-
webhooks: {
14195-
defaultHeaders: {
14196-
Authorization: "Bearer my-very-secured-token",
14197-
},
14198-
},
14199-
};
14200-
```
14201-
14202-
Language: JavaScript
14203-
File path: ./config/server.js
14204-
14205-
```js
14206-
module.exports = {
14207-
webhooks: {
14208-
defaultHeaders: {
14209-
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
14210-
},
14211-
},
14212-
};
14213-
```
14214-
14215-
---
14216-
Language: TypeScript
14217-
File path: ./config/server.ts
14218-
14219-
```ts
14220-
export default {
14221-
webhooks: {
14222-
defaultHeaders: {
14223-
Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
14224-
},
14225-
},
14226-
};
14227-
```
14228-
1422914234

1423014235
## entry.create
1423114236
Description: Example payload

‎docusaurus/static/llms-full.txt‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5993,34 +5993,44 @@ Most of the time, webhooks make requests to public URLs, therefore it is possibl
59935993

59945994
To prevent this from happening you can send a header with an authentication token. Using the Admin panel you would have to do it for every webhook.
59955995

5996-
:::tip Verify signatures
5997-
In addition to auth headers, sign webhook payloads and verify signatures server‑side to prevent tampering and replay attacks.
5996+
Another way is to define `defaultHeaders` to add to every webhook request.
59985997

5999-
- Generate a shared secret and store it in environment variables
6000-
- Have the sender compute an HMAC (e.g., SHA‑256) over the raw request body plus a timestamp
6001-
- Send the signature (and timestamp) in headers (e.g., `X‑Webhook‑Signature`, `X‑Webhook‑Timestamp`)
6002-
- On receipt, recompute the HMAC and compare using a constant‑time check
6003-
- Reject if the signature is invalid or the timestamp is too old to mitigate replay
6004-
6005-
Learn more:
6006-
-
5998+
You can configure these global headers by updating the file at `./config/server`:
60075999

60086000
</Tabs>
60096001

6010-
Additional external examples:
6011-
-
6002+
</TabItem>
60126003

60136004
</Tabs>
60146005

60156006
</TabItem>
60166007

60176008
</Tabs>
60186009

6019-
</TabItem>
6010+
If you are developing the webhook handler yourself you can now verify the token by reading the headers.
6011+
6012+
### Verifying signatures
6013+
6014+
In addition to auth headers, it's recommended to sign webhook payloads and verify signatures server‑side to prevent tampering and replay attacks. To do so, you can use the following guidelines:
6015+
6016+
- Generate a shared secret and store it in environment variables
6017+
- Have the sender compute an HMAC (e.g., SHA‑256) over the raw request body plus a timestamp
6018+
- Send the signature (and timestamp) in headers (e.g., `X‑Webhook‑Signature`, `X‑Webhook‑Timestamp`)
6019+
- On receipt, recompute the HMAC and compare using a constant‑time check
6020+
- Reject if the signature is invalid or the timestamp is too old to mitigate replay
6021+
6022+
<details>
6023+
<summary>Example: Verify HMAC signatures (Node.js)</summary>
6024+
6025+
Here is a minimal Node.js middleware example (pseudo‑code) showing
60206026

60216027
</Tabs>
60226028

6023-
If you are developing the webhook handler yourself you can now verify the token by reading the headers.
6029+
Here a few additional external examples:
6030+
-
6031+
-
6032+
<br />
6033+
</details>
60246034

60256035
<!--- ### Usage
60266036

0 commit comments

Comments
 (0)