Webhooks
What are Webhooks?
Webhooks are used for inbound POST requests to your API. Instead of polling for data (which might be inefficient and result in timing issues), webhooks send data directly to your API in real time.
Webhooks are specified in Endgrate as body parameters when initiating a session or triggering a push/pull. They are defined as an object with an endpoint and metadata.
"{type}_webhook": {
"endpoint": "https://httpbin.org/post",
"metadata": {
"user_id": 1
}
}
The endpoint
attribute is where Endgrate will POST to.
The metadata
attribute is optional. If included, Endgrate will include this object in the POST request to your webhook. For example, you may want to include a user identifier so that when receiving data you don't have to derive the user from the session.
By default, Endgrate will wait until a response is received from your API endpoint before initiating subsequent calls. You can disable this and allow Endgrate to make concurrent calls to your webhooks using the webhook_concurrency
flag as a body parameter.
{
"webhook_concurrency": true
}
For additional information, read the API reference — specifically, the callbacks section of the initiate endpoint you are using contains the supported webhook callbacks along with their payload formats.
Webhook Types
Webhooks are available for the following actions, we'll go more in-depth for each of these webhooks in future guides:
Completed Webhook
Endgrate will POST to this webhook whenever a transfer is completed. This is useful if you want to display a completion message to your users or call the GET api/pull/data endpoint or GET api/push/data endpoint afterwards (we'll review these endpoints in later guides).
Configuration Webhook
Endgrate will POST to this webhook when the session is configured by the user. This is useful if you want to get the integration provider chosen, passthrough field formats, and passthrough schema information without polling the GET api/session/configuration endpoint (we'll review this endpoint in a later guide).
Pull Data Webhook
Endgrate will POST to this webhook whenever new data is received. This is useful if you want to get transfer data without polling the GET api/pull/data endpoint (we'll review this endpoint in a later guide).
Push Data Webhook
Endgrate will POST to this webhook whenever new data is received. This is useful if you want to get transfer data without polling the GET api/push/data endpoint (we'll review this endpoint in a later guide).
Error Webhook
Endgrate will POST to this webhook whenever an error occurs. This endpoint is useful if you want to get error information without polling the GET api/errors endpoint (we'll review this endpoint in a later guide).
Webhook Payload Format
For each webhook, reference the API documentation callbacks section for a comprehensive layout of each webhook payload.
Webhook Security
Endgrate automatically signs each webhook POST request with a custom X-Endgrate-Signature
header so you can verify its authenticity. This header is an encoded string representing the JSON data sent to the webhook, signed using HMAC-SHA1 using your Endgrate API key. Only you and Endgrate have access to your API key.
To validate incoming requests, follow the signature procedure and compare the generated signature with the signature included in the request. If the two signatures match, it can be confirmed that the request was sent by Endgrate.
import base64
import hmac
import json
from hashlib import sha1
# Your API key from https://dashboard.endgrate.com/settings.
key = os.environ['ENDGRATE_API_KEY'].encode()
# Use the incoming JSON data from Endgrate's request as the data variable.
raw = json.dumps(data).encode()
hashed = hmac.new(key, raw, sha1)
signature = base64.b64encode(hashed.digest()).decode("ascii")
# Compare generated signature to X-Endgrate-Signature.
if signature == headers["X-Endgrate-Signature"]:
print("VALID SIGNATURE")
Updated 5 months ago