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).

Reference

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).

Reference

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).

Reference

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).

Reference

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).

Reference

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")