Quiltt Logo

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.

This could be when:

  • a user's Profile is created or updated
  • a user's Connection is created or updated

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

You can subscribe to the following event types:

Event TypeDescription
profile.createdA Profile has been created
profile.updatedA Profile has been updated
profile.changedA Profile has been created or updated
connection.createdA Connection has been created
connection.updatedA Connection has been updated
connection.changedA Connection has been created or updated

Each event contains the affected data model. For example, the profile.created event includes the Profile model. You can find the structure of each event in our 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/subscriptions

Requests must include the following HTTP headers:

Authorization: Bearer {{API_SECRET}} Content-Type: application/json

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.

{ "name": "Profile Created", "targetUrl": "https://example.com/quiltt_webhook", "eventTypes": ["profile.created"] }

Here is an example request that will create a subscription to connection.updated events.

curl --request POST \ --url 'https://api.quiltt.io/v1/webhooks/subscriptions' \ --header 'Authorization: Bearer {{API_SECRET}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Connection Updates", "targetUrl": "https://example.com/webhooks/quiltt", "eventTypes": ["connection.updated"] }'

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.

FieldTypeDescription
eventTypesarray of stringsA list of event types included in this payload
eventsarray of objectsThe events that triggered the webhook

Each event is structured as an object with an id, type, and a record object.

FieldTypeDescription
idstringThe unique ID of the webhook that was sent
typestringThe event that triggered the webhook
recordobjectThe affected data model. You can find the structure of each model in our API documentation

See an example of the JSON payload below:

{ "eventTypes": ["profile.created"], "events": [ { "id": "2Zj5zzFU3a9abcZ1aYYYaaZ1", "type": "profile.created", "record": { "userId": "897829c0-c580-4111-b25d-558aeb4efe3e", "environmentId": "da34ef2d-2bae-47fb-b180-110b5a8be5ea", "name": "Joe Allen Maldonado-Passage", "email": "[email protected]", ... } } ] }

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.

require 'sinatra' require 'json' # Using Sinatra post '/quiltt_webhook' do payload = request.body.read webhook = JSON.parse(payload, symbolize_names: true) webhook[:events].each do |event| case event[:type] when 'profile.created' profile = event[:record] # contains the profile data puts profile[:name] when 'connection.created' connection = event[:record] # contains the connection data puts connection[:id] else puts "Unhandled event #{event[:type]}" end end status 200 end

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.