Quiltt Logo

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:

TypeDescription
account.verifiedAn Account has been successfully verified and ACH numbers are now available via API.
connectionAll Connection-related events.
connection.synced.successfulA Connection has synced successfully.
profile.createdA Profile has been created.
connection.synced.errored.repairableA Connection has entered an error that must be resolved using the Reconnect flow

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.

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.

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

{
  "environment": {
    "id": "env_12uGLpOocVGvQYY9sFsOC6",
    "mode": "PRODUCTION",
    "metadata": null
  },
  "eventTypes": ["connection.synced.successful"],
  "events": [
    {
      "id": "evt_12sDfIGkY96vVvNvTqNfn9",
      "type": "connection.synced.successful",
      "profile": {
        "id": "p_12uGLpPexyTkZCcJJntSjb",
        "uuid": "018a72f8-5434-7262-a029-a186fb0c5f33",
        "metadata": {
          "my_internal_user_id": "12345"
        }
      },
      "record": {
        "id": "conn_12uGLpQUjSjdQqpIYoEVdQ",
        "provider": "MX",
        "status": "SYNCED",
        "metadata": null,
        "createdAt": "2023-09-08T04:06:32Z",
        "updatedAt": "2023-10-03T18:33:03Z"
      }
    }
  ]
}

See the Webhooks Schemas guide for the full list of event types and object schemas.

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

Webhooks are provided with a timestamp and a HMAC256 Signature, with a per subscription key, to allow you to verify that each message is issued by Quiltt, is intended for you, is received unmodified, and is not being repeated.

To verify the message is valid:

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

Link to this section#API Reference

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