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 push data directly to your API in real time.
Specifying Webhooks
Webhooks are specified in Endgrate when creating a session using any of the initiate endpoints:
Webhooks are defined as an object with an endpoint and metadata.
"{type}_webhook": {
"endpoint": "https://httpbin.org/post",
"metadata": {
"user_id": 1
}
},
"webhook_concurrency": false
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 on the initiate endpoint.
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:
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.
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, any passthrough schemas, or passthrough fields without polling the GET api/session/configuration endpoint.
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.
The data webhook also supports the continuous
flag. When this option is turned on, Endgrate will continuously trigger transfers on your behalf, polling for new data every 15 minutes.
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.
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. For reference, Python code is attached below.
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 7 months ago