Webhooks and Canopy

Activity that occurs in Canopy drives many downstream dependent actions. For example, sending email or text notifications to borrowers, executing logic in response to missed borrower payments, and more. All events that occur within the lifecycle of any borrowers on Canopy send webhook notifications for your dependent systems.

Organization-level Webhook URL

To assign your webhook URL to your Canopy organization, navigate to the “App Keys” page from the top right account dropdown. Under the Webhook URL section, paste your webhook URL into that input and hit the save button. Once configured in the Canopy UI, this URL will receive the following events.

Delivery Guarantees

Webhook messages have an ‘at least once’ guarantee. In order to facilitate this, a message may be delivered more than once. It is up to the receiver to detect duplicate messages. This can currently be done with the hmac_signature.

Ordering

There is no guarantee on delivery order of webhooks. If there is an error in receiving the webhook there will be a retry which might change the ordering of webhooks.

Response Pattern

Events will hit your webhook URL in the following pattern:

{
  "event": String, // The event name
  "data": Object, // The webhook payload
  "hmac_signature": String // The signature of the field "data"
}

<aside> 🧠 Your endpoint must respond with a 200 or 202

</aside>

Other response codes and Retry

• Events associated with error codes 429 and 5XX are retried before sent to dead letter queue (DLQ).
• Events associated with error codes 1XX, 3XX, and 4XX (excluding 429) aren't retried before sent to DLQ.
• Canopy will retry a single webhook event with exponential backoff, with the first retry 1 minute after the first failure, and will stop with the last retry approximately 24 hours after the first failure.
• The endpoint will pause if several error codes are received consecutively or if one 401 code is received
• Events stored in the dead letter queue (DLQ) are kept for 5 days, and you have the option to resend all DLQ events back to your webhook endpoint. A single put on the Canopy API route /organization/subscribe/replay_failed_events will replay all failed events to your webhook endpoint again.

Verifying HMAC Signatures

• You can verify the key on any HMAC library with encryption SHA256 and on Base64. This algorithm needs to be applied on the payload data field, and needs to be equal to the hmac_signature field.