Navigation

Webhook Requests & Responses

Overview

Depending on the service, incoming webhooks offer several ways to validate requests and customize the response that Stitch sends back to the external service.

Request Validation Methods

To validate that a webhook request is coming from a trusted source, some external services require that incoming requests incorporate a secret string in one of several prescribed manners. Other services, like the HTTP service, allow you to optionally require request validation.

There are two type of Request Validation for webhooks: Payload Signature Verification and Secret as a Query Parameter.

Note

For maximum security, programmatically generate the secret string using a secure package such as the Python secrets module. Make sure that you do not publish the secret or include it in your version control system.

Payload Signature Verification

The Verify Payload Signature request validation option requires that incoming requests include a hexadecimal-encoded HMAC SHA-256 hash generated from the request body and secret string in the X-Hook-Signature header.

Example

Consider the following webhook request body and secret:

const body = { "message":"MESSAGE" }
const secret = 12345

The following Stitch function generates the hash for this body and secret:

// Generate an HMAC request signature
exports = function(secret, body) {
  // secret = the secret validation string
  // body = the webhook request body
  return utils.crypto.hmac(EJSON.stringify(body), secret, "sha256", "hex");
}
// Returns: "828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862"

The hash value must be assigned to the X-Hook-Signature HTTP request header on every request:

X-Hook-Signature:sha256=<hex-encoded-hash>

To test that the request was properly signed, we could run the following curl command:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Hook-Signature:sha256=828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862" \
  -d '{"message":"MESSAGE"}' \
  <webhook URL>

Secret as a Query Parameter

The Require Secret as Query Param request validation option requires that incoming requests include the specified secret string as a query parameter appended to the end of the URL.

Example

Consider a webhook configured to use a secret value of 12345. All requests must be made to the webhook URL appended with the secret as a query parameter:

<webhook URL>?secret=12345

To test that requests to this URL are properly verified, we could run the following curl command:

curl -H "Content-Type: application/json" \
     -d '{ "message": "HELLO" }' \
     -X POST '<webhook URL>?secret=12345'

Webhook Response Object

Stitch automatically passes a response object that represents the webhook’s HTTP response as the second argument to webhook functions. The following table lists the available methods for modifying the response object:

Method Arguments Description
setStatusCode(code) code integer

Set the HTTP response status code.

Example

response.setStatusCode(201);
setBody(body) body string or BSON.Binary

Set the HTTP response body.

If body is a string, it will be encoded to BSON.Binary before being returned.

Example

response.setBody(
  "{'message': 'Hello, World!'}"
);
setHeader(name, value)
name string
value string

Set the HTTP response header specified by name to the value passed in the value argument. This overrides any other values that may have already been assigned to that header.

Example

response.setHeader(
  "Content-Type",
  "application/json"
);
addHeader(name, value)
name string
value string

Set the HTTP response header specified by name to the value passed in the value argument. Unlike setHeader, this does not override other values that have already been assigned to the header.

Example

response.addHeader(
  "Cache-Control",
  "max-age=600"
);

response.addHeader(
  "Cache-Control",
  "min-fresh=60"
)