Webhooks

Webhooks enable you to subscribe to changes to your data in Quiltt, without having to poll for updates.

For example, you can be notified when a Connection is synced or enters an error state, or when an Account is verified for money movement operations.

Link to this section#How It Works

When a subscribed event occurs, Quiltt will send a POST request to your registered targetUrl, with a JSON payload containing the event types and events that triggered the webhook. This allows you to execute actions in your system based on changes in Quiltt.

Link to this section#Event Types

Below are some of the events you can subscribe to:

Type	Description
profile.created	A Profile has been created.
connection.synced.successful	A Connection has synced successfully.
connection.synced.errored.repairable	A Connection has entered an error that must be resolved using the Reconnect flow
account.verified	An Account has been successfully verified and ACH numbers are now available via the Account Numbers API.

Each event payload will return information about the relevant data model and associated Profile. For example, the connection.created event will include information about the created Connection, along with the associated Profile.

See the Webhooks Schema reference for the full list of event types and object schemas.

Link to this section#Webhook Payload

The webhook payload will include a list of eventTypes and a list of events that occured. Each event is structured as an object with an id, type, profile and record attributes. Certain event types also provide an optional metadata attribute.

Here's an example payload for a connection.synced.successful event:

Link to this section#Handling Events

Your endpoint should respond back with a 2xx HTTP response code to indicate that your system has successfully processed the payload.

The webhooks system is designed to be resilient to both network delivery issues and service outages on the receiver's end. If your endpoint does not return a 2xx HTTP response code, Quiltt will automatically retry up to 3 times per delivery attempt. On PRODUCTION environments, Quiltt will make up to 20 delivery attempts, using an exponential backoff between each delivery attempt.

Link to this section#Webhook Verification

All Quiltt Webhooks are timestamped and signed with an HMAC256 signature, using a unique per-Subscription secret key. This allows you to verify that each message was issued by Quiltt, intended for your system, and has not been tampered with.

To verify the message is valid, check the headers of the incoming Webhook:

1. Ensure that the Quiltt-Timestamp header (Unix Epoch time) is within 5 minutes of current UTC time.
2. Validate that Quiltt-Signature header matches a Base64-encoded HMAC-SHA256 of version+timestamp+payload. The current version is 1.

Here's an example of how to construct and verify the signature in Ruby:

See the Setting up Webhook guide for complete code examples.

Link to this section#API Reference

See the Webhooks API Reference for full documentation of the subscription endpoints and the JSON payload we send to you.