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.

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, any passthrough schemas, or passthrough fields without polling the GET api/session/configuration endpoint.

Reference

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.

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.

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