Webhooks
Webhooks
Webhooks provide a way for the Quartr API to send real-time updates to your application when certain events occur. By setting up webhooks, you can receive notifications about event changes directly to your specified endpoint. In this section, we will cover how to manage webhook subscriptions and the requirements for receiving endpoints.
Managing Webhook Subscriptions
You can manage webhook subscriptions through the Quartr API by registering, unregistering, and listing your subscriptions.
Available webhook subscriptions
Each webhook subscription type can be registered for either all companies or a list of companies of interest. Each type has a unique list.
This is the list of webhook subscriptions:
-
“eventCreated” (Sent when a new event is created)
-
“eventDeleted” (Sent when an event is deleted)
-
“dateChanged” (Sent when an events date is changed)
-
“audioAdded” (Sent when there is an audio recording available for the event)
-
“transcriptAdded” (Sent when a transcript file is added to an event)
-
“slidesAdded” (Sent when a slide deck is added to an event)
-
“reportAdded” (Sent when a report is added to an event)
-
“liveStarted” (Sent when an audio stream goes live for an event)
-
“willBeLive“ (Sent when live coverage of the event is confirmed, meaning the event will be covered live on the platform when it starts.)
Registering a webhook
To register a webhook, make a request to the Register Webhook endpoint with the desired subscriptionType and targetUrl as query parameters.
For example, to subscribe to event live state updates:
POST https://api.quartr.com/public/v1/webhooks/register?subscriptionType=liveStarted&targetUrl=https://example.com/webhookA successful response will have the following format:
{ "status": "success", "message": "Webhook registered successfully.", "data": { "typeName": "event_live_state_update", "typeDescription": "An event live state update", "targetUrl": "https://example.com/webhook" } }Subscribing to Lists of Companies
To subscribe to a list of companies, you can include a combination of Quartr companyIds, tickers, and ISIN codes in the body of the Register Webhook request. Including the country with the ticker is optional, but it may help to avoid overlaps when the same ticker is used in different countries.
Here is a sample request body for subscribing to a list of companies by providing a combination of companyIds, tickers, and ISIN codes:
{
"companyIds": ["001", "002", "003"],
"tickers": [
{"ticker": "AAPL", "country": "US"},
{"ticker": "GOOGL", "country": "US"}
],
"isins": ["US0378331005", "US02079K1079"]
}Not supplying any of these parameters in the request will result in following all available companies for that particular webhook subscription.
Unregistering a webhook
To unregister a webhook, make a request to the Unregister Webhook endpoint with the subscriptionType as a query parameter.
For example, to unsubscribe from event live state updates:
POST https://api.quartr.com/public/v1/webhooks/unregister?subscriptionType=event_live_state_updateListing webhook subscriptions
To list your webhook subscriptions, make a request to the Get Webhook Subscriptions endpoint.
GET https://api.quartr.com/public/v1/webhooks/subscriptionsReceiving Endpoint Requirements
To ensure proper handling of webhook notifications, your receiving endpoint should meet the following requirements:
-
Use HTTPS: Your endpoint must be secured with HTTPS to ensure the data transmitted is encrypted and secure.
-
Acknowledge receipt: Your endpoint should respond with an HTTP status code in the 2xx range to acknowledge receipt of the notification. Failure to acknowledge receipt may result in retries from the Quartr API.
-
Handle retries: The Quartr API may retry sending notifications if your endpoint does not acknowledge receipt or if it encounters an error. Be prepared to handle retries and deduplicate events based on their unique identifiers.
-
Webhook notifications contain event data in the request body, so ensure your receiving endpoint can parse and handle the data appropriately.
Example response
After successful registration for a specific webhook type, your designated endpoint is set to receive POST requests. These requests will include details such as the webhook type name and a unique identifier (uuid) to assist in preventing potential duplicate transactions due to repeated sends. Additionally, these requests will include both the new and previous state of the object properties.
For instance,
The request might contain an object like the following:
{
"name": "audioAdded",
"uuid": "6a717681-55ca-4b29-a0b9-de82ef1636bf",
"data": {
"companyId": "14464",
"event": {
"audioUrl": null,
"reportUrl": null,
"pdfUrl": null,
"eventId": 64661,
"eventTitle": "Q2 2023",
"eventDate": "2023-07-25T14:00:00.000Z",
"companyId": 14464,
"qnaTimestamp": null,
"fiscalPeriod": "Q2",
"fiscalYear": "2023",
"eventType": {
"type": "Q2",
"secondaryType": "Earnings Call"
},
"audioDuration": null,
"slidesPreviewUrl": null,
"transcriptUrl": null,
"backlinkUrl": "https://quartr.com/companies/14464?utm_source=api&utm_medium=0&utm_campaign=14464_64661"
},
"previousProperties": {
"audioUrl": null,
"reportUrl": null,
"pdfUrl": null,
"eventId": 64661,
"eventTitle": "Q2 2023",
"eventDate": "2023-07-21T20:00:00.000Z",
"companyId": 14464,
"qnaTimestamp": null,
"fiscalPeriod": "Q2",
"fiscalYear": "2023",
"eventType": {
"type": "Q2",
"secondaryType": "Earnings Call"
},
"audioDuration": null,
"slidesPreviewUrl": null,
"transcriptUrl": null,
"backlinkUrl": "https://quartr.com/companies/14464?utm_source=api&utm_medium=0&utm_campaign=14464_64661"
}
}
}Webhook PayloadsCopied!
{
"name": "liveStarted",
"uuid": "87e879d2-99f8-4941-8825-e6ccf4477b48",
"data": {
"companyId": 9999,
"event": {
"eventId": 1234,
"eventTitle": "Mock Event Q1 2024",
"eventDate": "2024-01-01T00:00:00.000Z",
"companyId": 9999,
"qnaTimestamp": null,
"fiscalPeriod": "Q1",
"fiscalYear": "2024",
"eventType": {
"type": "Q1",
"secondaryType": "Mock Earnings Call"
},
"audioDuration": null,
"slidesPreviewUrl": null,
"audioUrl": null,
"pdfUrl": null,
"slidesUrl": null,
"reportUrl": null,
"transcriptUrl": "https://quartr.com/",
"transcriptViewerUrl": "https://quartr.com/",
"backlinkUrl": "https://quartr.com/",
"liveState": {
"liveAudioState": "live",
"liveUrl": "https://quartr.com/",
"wentLiveAt": "2024-03-28T11:53:25.886Z"
}
},
"data": {
"eventId": 1234,
"eventTitle": "Mock Event Q1 2024",
"eventDate": "2024-01-01T00:00:00.000Z",
"companyId": 9999,
"qnaTimestamp": null,
"fiscalPeriod": "Q1",
"fiscalYear": "2024",
"eventType": {
"type": "Q1",
"secondaryType": "Mock Earnings Call"
},
"audioDuration": null,
"slidesPreviewUrl": null,
"audioUrl": null,
"pdfUrl": null,
"slidesUrl": null,
"reportUrl": null,
"transcriptUrl": "https://quartr.com/",
"transcriptViewerUrl": "https://quartr.com/",
"backlinkUrl": "https://quartr.com/",
"liveState": {
"liveAudioState": "live",
"liveUrl": "https://quartr.com/",
"wentLiveAt": "2024-03-28T11:53:25.886Z"
}
},
"previousProperties": {
"eventId": 1234,
"eventTitle": "Mock Event Q1 2024",
"eventDate": "2024-01-01T00:00:00.000Z",
"companyId": 9999,
"qnaTimestamp": null,
"fiscalPeriod": "Q1",
"fiscalYear": "2024",
"eventType": {
"type": "Q1",
"secondaryType": "Mock Earnings Call"
},
"audioDuration": null,
"slidesPreviewUrl": null,
"audioUrl": null,
"pdfUrl": null,
"slidesUrl": null,
"reportUrl": null,
"transcriptUrl": "https://quartr.com/",
"transcriptViewerUrl": "https://quartr.com/",
"backlinkUrl": "https://quartr.com/",
"liveState": {
"liveAudioState": "live",
"liveUrl": "https://quartr.com/",
"wentLiveAt": "2024-03-28T11:53:25.886Z"
}
}
}
}