Anatomy of a Webhook HTTP Request

An HTTP message is a typical means by which two techniques, normally a server and a shopper, change knowledge. We usually refer to every HTTP message as an HTTP request or an HTTP response.

Webhook HTTP requests are a selected subset of HTTP requests which switch knowledge between techniques based mostly on occasions in these techniques. Webhooks are used with many event-driven integrations.

When working with our prospects, we discover that some are new to webhooks and wish to study extra about what contains a webhook HTTP request. For those who’re in that class, this submit ought to assist.

What Are the Sections of a Webhook HTTP Request?

Host: instance.com
user-agent: curl/7.79.1
settle for: */*
myapp-hmac-sha1: f237e4a4062590a674b0adc1e84614196aae79f4
myapp-api-key: 90B649F2-70F2-4180-95BC-951F5D832F0D
content-type: utility/json
content-length: 188

{
  "orderId": "abc-123",
  "state": "replace",
  "updates": [
    { "action": "remove", "item": "widgets", "quantity": 5 },
    { "action": "add", "item": "gadgets", "quantity": 20 }
  ]
}

curl https://instance.com/ 
 --verbose 
 --request POST 
 --header 'myapp-hmac-sha1: f237e4a4062590a674b0adc1e84614196aae79f4' 
 --header 'myapp-api-key: 90B649F2-70F2-4180-95BC-951F5D832F0D' 
 --header 'content-type: utility/json' 
 --data '{
  "orderId": "abc-123",
  "state": "replace",
  "updates": [
    { "action": "remove", "item": "widgets", "quantity": 5 },
    { "action": "add", "item": "gadgets", "quantity": 20 }
  ]
}'

> POST / HTTP/2
> Host: instance.com
> user-agent: curl/7.79.1
> settle for: */*
> myapp-hmac-sha1: f237e4a4062590a674b0adc1e84614196aae79f4
> myapp-api-key: 90B649F2-70F2-4180-95BC-951F5D832F0D
> content-type: utility/json
> content-length: 188
>
* We're fully uploaded and tremendous
< HTTP/2 200
< accept-ranges: bytes
< cache-control: max-age=604800
< content-type: textual content/html; charset=UTF-8
< date: Thu, 02 Jun 2022 20:26:44 GMT
< etag: "3147526947"
< expires: Thu, 09 Jun 2022 20:26:44 GMT
< last-modified: Thu, 17 Oct 2019 07:18:26 GMT
< server: EOS (vny/044E)
< content-length: 1256

Inspecting the Begin Line

Methodology

Request strategies (verbs) outline the motion carried out by an HTTP request. At current, HTTP helps eight strategies:

• DELETE
• GET
• HEAD
• OPTIONS
• PATCH
• POST
• PUT
• TRACE

Nonetheless, webhooks solely use a subset of those. POST is used more often than not, even when knowledge is being up to date or deleted as an alternative of created. Sometimes, we would see a webhook use GET to confirm {that a} webhook endpoint exists. Much less generally, PUT and PATCH are used to change/substitute knowledge. And doubtless least widespread of all, some webhooks use DELETE.

URL

The commonest URL for a webhook is one thing like https://instance.com/my-webhook.

Some apps append an absolute path to the URL to let you realize the document kind that is being requested: for instance, https://instance.com/my-webhook/order-confirmation when an order is confirmed.

The URL with a question string is a widespread sample for internet web page requests (corresponding to serps) the place some worth is appended to the tip of the usual URL https://instance.com/my-webhook?param1=Param-Value1&param2=Param-Value2. Whereas rare, some apps use question strings to ship metadata through the URL as an alternative of in customized headers.

Model

The model is simply that, the model of the HTTP protocol used for the request. It would typically be HTTP/1.1 or HTTP/2. Whereas webhook HTTP requests embody the model, it normally has no influence and is there to make sure that the HTTP request is legitimate.

Inspecting the Headers

Default Headers

Many headers are default and are mechanically generated by the supply system. Listed here are a couple of default headers generally used with webhooks:

• Content material-Sort: Describes the info despatched within the physique (instance: utility/json)
• Person-Agent: Describes the HTTP shopper used for the request (instance: Mozilla/5.0)
• Content material-Size: Defines the scale of the request in bytes.
• Settle for or Settle for-Encoding: Defines the kind of response anticipated.

Customized Headers

myapp-hmac-sha1: f237e4a4062590a674b0adc1e84614196aae79f4
myapp-api-key: 90B649F2-70F2-4180-95BC-951F5D832F0D

Inspecting the Physique

{"renderId":51266,"s3Bucket":"test-customer-renders","standing":"full"}

curl 'https://instance.io/webhook/' 
  --request POST 
  --header "Content material-Sort: multipart/form-data" 
  --form individual='{"firstname":"Sam","lastname":"McElhaney"};kind=utility/json' 
  --form photograph=@sam.jpeg 
  --form resume=@resume.pdf

> POST /webhook HTTP/2
> Host: instance.com
> user-agent: curl/7.79.1
> settle for: */*
> content-length: 73686
> content-type: multipart/form-data; boundary=------------------------0c985f7380ec6342

--------------------------0c985f7380ec6342
Content material-Disposition: form-data; title="individual"
Content material-Sort: utility/json

{"firstname":"Sam","lastname":"McElhaney"}
--------------------------0c985f7380ec6342
Content material-Disposition: form-data; title="photograph"; filename="sam.jpeg"
Content material-Sort: picture/jpeg

SOME BINARY DATA...
--------------------------0c985f7380ec6342
Content material-Disposition: form-data; title="resume"; filename="resume.pdf"
Content material-Sort: utility/pdf

%PDF-1.3
MORE BINARY DATA
%%EOF
--------------------------0c985f7380ec6342--

With an rising variety of firms (from Salesforce to Shopify) implementing webhooks, this know-how is quick turning into the usual for SaaS integrations. Webhooks are easy to know and implement, and they’re extremely versatile – permitting you to make them as easy or complicated as the info requires.