- Stitch >
- External Services >
- Reference
Webhook Requests & Responses¶
On this page
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:
The following Stitch function generates the hash
for this body
and secret
:
The hash value must be assigned to the X-Hook-Signature
HTTP
request header on every request:
To test that the request was properly signed, we could run the
following curl
command:
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:
To test that requests to this URL are properly verified, we could run
the following curl
command:
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 Example response.setBody(
"{'message': 'Hello, World!'}"
);
|
setHeader(name, value) |
name stringvalue string |
Set the HTTP response header
specified by Example response.setHeader(
"Content-Type",
"application/json"
);
|
addHeader(name, value) |
name stringvalue string |
Set the HTTP response header
specified by Example response.addHeader(
"Cache-Control",
"max-age=600"
);
response.addHeader(
"Cache-Control",
"min-fresh=60"
)
|