Using ConnectReport Callbacks (Webhooks)

ConnectReport Callbacks are used to tell other applications when events occur in ConnectReport.

They are technically webhooks, a term for user-defined callbacks in web applications – put simply, they allow you to inform your own applications in real time when useful events occur in ConnectReport, such as a successful report task execution.  

localhost_4700_admin_users__2_.png

Unlike typical APIs, Callbacks (and Webhooks) are efficient for both services and consumers because they prevent the need to poll for new data at short frequencies to retrieve data in real time.  

Callbacks may be thought of as "reverse APIs". Instead of calling the ConnectReport API,  ConnectReport Server will call your API with new data as it becomes available. 

Example use case: Publishing to OneDrive

Imaging your colleagues have requested that all new reports tagged "sales" be published in Excel format in the Sales department's OneDrive folder. To accomplish this, you configure a callback using the post report task trigger. In your callback handler code, you make a few ConnectReport API requests to get information on the tags for the report and to export it to XLSX format. 

Each time ConnectReport completes execution of a report task, the server will make an HTTP POST request to the Callback URL you configure. The request will include a payload with metadata from the report task, including whether it executed successfully, the time it completed, any error information if applicable, and much more. You can use the data sent to your callback handler to query the ConnectReport APIs to determine the tags that are applied to the report task and render the report to Excel format. From there, you make a request to Microsofts API for OneDrive to store the rendered report. 

Request specifications

The method for all callbacks is HTTP POST. Upon executing, the Callback will make a POST request to the URL you specify. 

The content type for all callback payloads is JSON. 

Supported callback triggers

Pre report task

This trigger is executed immediately before a report task begins executing. You can use it to inform your own applications when a report task has kicked off. 

Payload properties and examples

  • reportTask: 
    • id: 'b9e574a9-fb52-443b-a1aa-1eed82a8b1ba'
    • title: 'Weekly sales overview'
    • reportTaskId: '20cf12d4-4c6f-4212-8510-14ddbbd6ae66'
    • templateId: '8692affa-7eb4-40b5-ba15-04ba8954a90c'
    • startOn: '2020-01-12T00:55:32.941Z'
    • endOn: '2021-01-12T00:55:32.941Z'
    • frequency: 'Monthly'
    • filterCycleId: '487a5c2f-fcae-4ad1-9bfa-444140818446'
    • createdAt: '2020-01-12T00:51:07.536Z'
    • lastSavedAt: '2020-01-12T00:51:07.659Z'
    • templateHtml: '<div class="report-master-meta">...</div>'
  • trigger: 'preReportTask'

Post report task

This trigger is executed immediately after a report task has completed. You can use it to implement behavior you want to occur whenever a report task completes, such as publishing the report to a file share or sending a text message through an API like Twilio to notify people that is has been published. 

Payload properties and examples

  • reportTask: 
    • id: 'b9e574a9-fb52-443b-a1aa-1eed82a8b1ba'
    • title: 'Weekly sales overview'
    • reportTaskId: '20cf12d4-4c6f-4212-8510-14ddbbd6ae66'
    • templateId: '8692affa-7eb4-40b5-ba15-04ba8954a90c'
    • startOn: '2020-01-12T00:55:32.941Z'
    • endOn: '2021-01-12T00:55:32.941Z'
    • frequency: 'Monthly'
    • filterCycleId: '487a5c2f-fcae-4ad1-9bfa-444140818446'
    • createdAt: '2020-01-12T00:51:07.536Z'
    • lastSavedAt: '2020-01-12T00:51:07.659Z'
    • templateHtml: '<div class="report-master-meta">...</div>'
  • trigger: 'postReportTask'
  • status: 'success' || 'failure'
  • error: undefined || 'Report task failed due to <Error_Reason>'