Webhooks
Webhooks enable you to react to changes in our systems without polling for data. We notify your system in real time when a specific event has happened. Example events are when a Profile is created, updated or deleted, or when a Connection is synced or enters an error state.
Link to this section#How we use Webhooks
We provide multiple event types you can subscribe to. When relevant events occur, Quiltt will send a notification to the subscribed endpoint via HTTPS. The notification contains a JSON payload with the event types and the events that have occurred. This allows you to execute actions in your system based on changes in Quiltt.
Link to this section#Event Types
Below are a few of the events you can subscribe to::
| Event Type | Description |
|---|---|
profile | All Profile events |
profile.created | A Profile has been created |
connection | All Connection events |
connection.synced.successful | A Connection has synced successfully |
connection.synced.errored | A Connection sync resulted in an error |
Each event payload will return information about the Profile and the affected data model. For example, the connection.created event will include information about the created Connection, along with the associated Profile.
You can find the full list of event types and schemas in the Admin API Reference.
Link to this section#How to Subscribe to a Webhook
You can subscribe to events by sending a POST request to our webhooks subscriptions endpoint:
POSThttps://api.quiltt.io/v1/webhooks/subscriptionsRequests must include the following HTTP headers:
Requests must include a JSON body with the name of your subscription, a list of event types, and the target URL that should receive the webhooks.
Here is an example request that will create a subscription to connection.updated events.
Successful responses will return a 201 HTTP response code.
Link to this section#How to Receive a Webhook
When subscribed events occur, Quiltt will send a POST request to your targetUrl, with a JSON payload. The JSON payload will contain the relevant data about the event(s) that triggered the webhook.
Link to this section#Webhook Payload
The webhook payload includes a list of eventTypes and a list of events.
| Field | Type | Description |
|---|---|---|
eventTypes | array of stringsrequired | The types of events included in the Payload. |
events | array of objectsrequired | The events included in this Payload. |
Each event is structured as an object with an id, type, and a record object.
| Field | Type | Description |
|---|---|---|
id | stringrequired | The ID of the Event. |
type | stringrequired | The type of event that occurred. |
profile | object | The Profile associated with the event. |
record | object | The record associated with the event. |
See an example of the JSON payload below:
Link to this section#Sample Implementation
The following example shows how you could parse the received JSON payload and decide how to process the data of each event, based on its type. This example is using Ruby, but the logic will be similar in your language of choice.
Your endpoint should respond back with a 200 HTTP response code to indicate that you've successfully received the request. Otherwise, Quiltt will retry sending the request several times.
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.