Skip to content

Commit 1e14d60

Browse files
menewmanmenewman
authored
Clarify webhook docs (#60)
1 parent ffe7f2d commit 1e14d60

File tree

6 files changed

+58
-41
lines changed

6 files changed

+58
-41
lines changed

‎docs/graphql/index.css

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,11 @@ pre {
3232
}
3333

3434
pre > code {
35-
font-family: 'Fira Code', monospace;
35+
font-family: 'JetBrains Mono', monospace;
3636
}
3737

3838
.mono {
39-
font-family: 'Fira Code', monospace;
39+
font-family: 'JetBrains Mono', monospace;
4040
}
4141

4242
.page-container {

‎docs/graphql/index.html

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
<html lang="en">
33

44
<head>
5-
<link rel="preconnect" href="https://fonts.googleapis.com">
6-
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
7-
<link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;700&family=Work+Sans:wght@400;700&display=auto" rel="stylesheet">
8-
<link rel="icon" type="image/png" href="/images/favicon.png" sizes="32x32"/>
5+
<link rel="preconnect" href="https://fonts.googleapis.com">
6+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
7+
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&family=Work+Sans:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
8+
<link rel="icon" type="image/png" href="/images/favicon.png" sizes="32x32"/>
99
<title>CodeSignal GraphQL API</title>
1010
<meta name="description" content="GraphQL API documentation for the most advanced technical assessment solution on the market."/>
1111
<link type="text/css" rel="stylesheet" href="index.css" />

‎docs/index.css

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ h3 {
4444
}
4545

4646
.header {
47-
font-family: 'Fira Code', monospace;
47+
font-family: 'JetBrains Mono', monospace;
4848
}
4949

5050
.header-title {
@@ -71,5 +71,5 @@ h3 {
7171
.doc-link {
7272
font-size: 1.3em;
7373
display: block;
74-
font-family: 'Fira Code', monospace;
74+
font-family: 'JetBrains Mono', monospace;
7575
}

‎docs/index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<head>
55
<link rel="preconnect" href="https://fonts.googleapis.com">
66
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
7-
<link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;700&family=Work+Sans:wght@400;700&display=auto" rel="stylesheet">
7+
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&family=Work+Sans:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
88
<link rel="icon" type="image/png" href="/images/favicon.png" sizes="32x32"/>
99
<title>CodeSignal API for Developers</title>
1010
<meta name="description" content="Developer API documentation for the most advanced technical interview and assessment skills evaluation platform on the market."/>

‎docs/webhooks/index.css

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,15 +38,15 @@ pre {
3838
}
3939

4040
pre > code {
41-
font-family: 'Fira Code', monospace;
41+
font-family: 'JetBrains Mono', monospace;
4242
}
4343

4444
li:not(:first-child) {
4545
margin-top: 12px;
4646
}
4747

4848
.mono {
49-
font-family: 'Fira Code', monospace;
49+
font-family: 'JetBrains Mono', monospace;
5050
}
5151

5252
.page-container {

‎docs/webhooks/index.html

Lines changed: 47 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
11
<!DOCTYPE html>
22
<html lang="en">
33
<head>
4-
<link rel="preconnect" href="https://fonts.googleapis.com" />
5-
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
6-
<link
7-
href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;700&family=Work+Sans:wght@400;700&display=auto"
8-
rel="stylesheet"
9-
/>
4+
<link rel="preconnect" href="https://fonts.googleapis.com">
5+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
6+
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&family=Work+Sans:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
107
<link rel="icon" type="image/png" href="/images/favicon.png" sizes="32x32" />
118
<title>CodeSignal Webhook API</title>
129
<meta
@@ -40,7 +37,7 @@ <h2>Table of Contents</h2>
4037
<ul>
4138
<li><a href="#auth">Authentication</a></li>
4239
<li><a href="#eventhandling">Event handling</a></li>
43-
<li><a href="#retry">Retry policy</a></li>
40+
<li><a href="#retry">Errors and retry policy</a></li>
4441
<li><a href="#payloads">Webhook payloads</a></li>
4542
</ul>
4643
<li>Events for CodeSignal Assessments</li>
@@ -222,13 +219,24 @@ <h3 id="eventhandling">Event handling</h3>
222219
</p>
223220
</div>
224221
<div class="subsection">
225-
<h3 id="retry">Retry policy</h3>
222+
<h3 id="retry">Errors and retry policy</h3>
226223
<div>
227-
In the event of a failed webhook (due to timeout, a status code other than 200, or
228-
network issues), CodeSignal will attempt a maximum of 25 retries with exponential
229-
backoff according to the formula below. The number of seconds to wait is relative to
230-
the last failed attempt.
231-
<pre><code>secondsToWait = failCount^4 + 15 + (random(30) * (failCount + 1))</code></pre>
224+
<p>
225+
If CodeSignal receives any response other than a 200 OK from the endpoint,
226+
the endpoint will be marked unhealthy, and CodeSignal will attempt to resend the
227+
event after a delay (up to 25 attempts total).
228+
</p>
229+
<p>
230+
CodeSignal is looking for a 200 OK response from the endpoint URL in order to continue processing
231+
further events. Do <em>not</em> return 400 errors; they will not be respected and the webhook
232+
will be flagged as unhealthy. Instead, keep error-handling logic internal to your endpoint.
233+
</p>
234+
<p>
235+
The delay is calculated using an exponential backoff strategy. In other words,
236+
the retry window will be short at first but will increase if the endpoint keeps failing.
237+
The delay between each failure and the next attempt is calculated with the formula below.
238+
</p>
239+
<pre><code>secondsToWait = (failCount - 1)^4 + 15 + (random(30) * failCount)</code></pre>
232240
</div>
233241
<p>
234242
Assuming that <span class="mono">random(30)</span> always returns its average of 15,
@@ -238,75 +246,84 @@ <h3 id="retry">Retry policy</h3>
238246
<table>
239247
<thead>
240248
<tr>
241-
<th align="center">Previous failed attempts</th>
242-
<th align="center">Time since last attempt</th>
243-
<th align="center">Time since first attempt</th>
249+
<th align="center">Total failed attempts</th>
250+
<th align="center">Time until next attempt</th>
251+
<th align="center">Time until next attempt, from first failure</th>
244252
</tr>
245253
</thead>
246254
<tbody>
247255
<tr>
248-
<td align="center">0</td>
256+
<td align="center">1</td>
249257
<td align="center">30 seconds</td>
250258
<td align="center">30 seconds</td>
251259
</tr>
252260
<tr>
253-
<td align="center">1</td>
261+
<td align="center">2</td>
254262
<td align="center">46 seconds</td>
255263
<td align="center">1.3 minutes</td>
256264
</tr>
257265
<tr>
258-
<td align="center">2</td>
266+
<td align="center">3</td>
259267
<td align="center">1.2 minutes</td>
260268
<td align="center">2.5 minutes</td>
261269
</tr>
262270
<tr>
263-
<td align="center">3</td>
271+
<td align="center">4</td>
264272
<td align="center">2.6 minutes</td>
265273
<td align="center">5.1 minutes</td>
266274
</tr>
267275
<tr>
268-
<td align="center">5</td>
276+
<td align="center">6</td>
269277
<td align="center">12.2 minutes</td>
270278
<td align="center">23 minutes</td>
271279
</tr>
272280
<tr>
273-
<td align="center">10</td>
281+
<td align="center">11</td>
274282
<td align="center">2.8 hours</td>
275283
<td align="center">7.4 hours</td>
276284
</tr>
277285
<tr>
278-
<td align="center">13</td>
286+
<td align="center">14</td>
279287
<td align="center">8 hours</td>
280288
<td align="center">1 day</td>
281289
</tr>
282290
<tr>
283-
<td align="center">15</td>
291+
<td align="center">16</td>
284292
<td align="center">14 hours</td>
285293
<td align="center">2.1 days</td>
286294
</tr>
287295
<tr>
288296
<td align="center">24</td>
289-
<td align="center">3.8 days</td>
290-
<td align="center">20.5 days</td>
297+
<td align="center">3.2 days</td>
298+
<td align="center">16.6 days</td>
299+
</tr>
300+
<tr>
301+
<td align="center">25</td>
302+
<td align="center">n/a</td>
303+
<td align="center">n/a</td>
291304
</tr>
292305
</tbody>
293306
</table>
294307
<p>
295308
After the first few retries CodeSignal will also send an email notification to the
296309
owner emails associated with the webhook, if any. To make sure we don't spam you,
297-
CodeSignal will send at most one email a day for every webhook. This means that you
298-
will generally be notified about the 5th fail, the 14th fail, and every fail
299-
starting from the 16th.
310+
CodeSignal will only send emails for each webhook after the 5th failure, the 14th failure,
311+
and every failure starting from the 16th.
300312
</p>
301313
<p>
302314
When a webhook is unhealthy, events will be queued in the order they were triggered,
303-
and the queue will not be flushed until the first event in the queue is able to be
315+
and the queue will not be flushed until the first event in the queue can be
304316
processed successfully (by receiving a 200 OK response from the endpoint URL). If
305317
you are able to identify and resolve the issue with the endpoint URL, you can open
306318
the webhook settings modal, then test and save the fixed webhook in order to mark it
307319
as healthy again. Once it is marked as healthy, the webhook will immediately flush
308320
its queue of pending events.
309321
</p>
322+
<p>
323+
After 25 consecutive failed delivery attempts, the webhook will be disabled and the
324+
events queue will be cleared. You can re-enable the webhook after updating the endpoint
325+
to return a valid 200 OK response.
326+
</p>
310327
</div>
311328
<div class="subsection">
312329
<h3 id="payloads">Webhook payloads</h3>

0 commit comments

Comments
 (0)