Skip to main content
The webhook destination delivers work to an HTTP endpoint you run.

​
Credentials

Optional. Uses an HTTP Auth Headers credential to attach headers to every delivery.
N.B: Credential headers overwrite destination headers of the same name.

​
Request

Arklow makes the following request to your endpoint:
  • Method: POST
  • URL: the URL configured on the destination.
  • Headers:
    • All headers configured on the destination, plus the credential’s headers.
    • Content-Type: application/json
    • x-arklow-actionid: the id of the action being delivered.
    • x-arklow-attempt: the attempt number, starting at 0.
  • Body: the action’s payload, as JSON.

​
Response

A delivery settles by ack or nack. Your response can carry it in two ways: 
HTTP/1.1 200 OK
x-arklow-signaling: nack
x-arklow-signaling-val: 30
x-arklow-signaling takes ack, nack, or mod_ack. x-arklow-signaling-val carries the value in seconds, where one applies.
When both are present, the headers take precedence.

​
Signals

SignalEffect
ackThe action succeeds.
nackThe attempt fails and is redelivered. A value in seconds schedules the redelivery.
mod_ackHolds the action in ack_wait for the value in seconds, or 60 without one.

​
Unsignaled responses

A 2xx response with no signal follows the destination’s signaling config:
  • With {"enabled": true, "default": "ack"}, the action succeeds immediately.
  • Otherwise, the action waits in ack_wait for 60 seconds. An attempt that passes its deadline unsettled is redelivered under the next attempt number.
Delivery is at-least-once: the same unit of work can arrive more than once.

​
Settling later

A delivery can settle after the response, through the ingress endpoints /v1/ack, /v1/nack, and /v1/modack. Use the x-arklow-actionid and x-arklow-attempt from the delivery.
  • A settle applies only to the attempt it names.
  • Within nack terms: retry_at takes unix seconds and schedules the retry. retry: false makes the failure permanent. With neither set, Arklow schedules the retry itself.
  • mod_ack extends the settlement deadline by the given seconds.

​
Failures

Any other response classifies as follows:
Your responseWhat Arklow does
429Rate limited. retry-after is honored.
500 502 503 504Unavailable. Retried, and Arklow backs off.
408 409 425Retried.
other 4xxRejected. Retried after retry-after, or 60 seconds without one.
Retries carry the next attempt number and continue until the action times out.

​
Add a webhook to Arklow

1

Open the destinations page

Go to Destinations and click Create destination.
2

Pick the type

Set Destination Type to Webhook.
3

Configure the endpoint

Enter the URL. Add headers if your endpoint expects them.
4

Save

Click Create destination.

​
Special Notes

Arklow domains are not accepted as webhook targets.

​
Reference

API Reference