Releases

Pricing

Affiliates

Circleback Webhook Integration

The webhook integration in automations allows you to receive meeting notes, action items, transcript, insights, recording, and other metadata after meetings. Automations can also be shared to unify webhook integrations across your team.

Getting started

Follow these steps to start receiving webhook events from Circleback:

Open Automations and add a webhook step to an existing or new automation.
Enter the webhook endpoint URL and toggle on what you don’t like to be included in webhook requests.
Select Done and Save the automation.

Requests

Once configured, you’ll start receiving POST requests at the provided endpoint URL with a JSON body that includes the following fields:

id (number): Circleback meeting ID
name (string): meeting name
createdAt (string): meeting creation date formatted in ISO string
duration (number): meeting duration in seconds
url (string or null): URL of the virtual meeting (i.e. Zoom, Google Meet, Microsoft Teams)
recordingUrl (string or null): URL of the meeting’s recording file which is only valid for 24 hours (only available if saving meeting recordings is enabled in settings)
attendees (array of objects): meeting attendees
- name (string or null): attendee name from calendar event if joined via calendar or from meeting if joined via link
- email (string or null): attendee email, only available if joined via calendar
notes (string): Circleback meeting notes with Markdown formatting
actionItems (array of objects): array of action items created for meeting
- id (number): Circleback action item ID
- title (string): action item title
- description (string): action item description
- assignee (object or null): action item assignee object or null if unassigned
  - name (string or null): assignee name
  - email (string or null): assignee email
- status (string): action item status, one of PENDING, IN_PROGRESS, DONE, or CANCELED
transcript (array of objects): meeting transcript segments
- speaker (string): speaker name
- text (string): words spoken
- timestamp (number): timestamp in seconds that marks the beginning of the segment
insights (object):
- [insightName] (string object key): name of the user-created insight
  - array of objects
    - insight (string or object if insight has custom fields): the insight result
    - speaker (string or null): speaker the insight is associated with (if any)
    - timestamp (number or null): the timestamp in seconds the insight is associated with (if any)

Example

Getting started

Follow these steps to start receiving webhook events from Circleback:

Open Automations and add a webhook step to an existing or new automation.
Enter the webhook endpoint URL and toggle on what you don’t like to be included in webhook requests.
Select Done and Save the automation.

Requests

Once configured, you’ll start receiving POST requests at the provided endpoint URL with a JSON body that includes the following fields:

id (number): Circleback meeting ID
name (string): meeting name
createdAt (string): meeting creation date formatted in ISO string
duration (number): meeting duration in seconds
url (string or null): URL of the virtual meeting (i.e. Zoom, Google Meet, Microsoft Teams)
recordingUrl (string or null): URL of the meeting’s recording file which is only valid for 24 hours (only available if saving meeting recordings is enabled in settings)
attendees (array of objects): meeting attendees
- name (string or null): attendee name from calendar event if joined via calendar or from meeting if joined via link
- email (string or null): attendee email, only available if joined via calendar
notes (string): Circleback meeting notes with Markdown formatting
actionItems (array of objects): array of action items created for meeting
- id (number): Circleback action item ID
- title (string): action item title
- description (string): action item description
- assignee (object or null): action item assignee object or null if unassigned
  - name (string or null): assignee name
  - email (string or null): assignee email
- status (string): action item status, one of PENDING, IN_PROGRESS, DONE, or CANCELED
transcript (array of objects): meeting transcript segments
- speaker (string): speaker name
- text (string): words spoken
- timestamp (number): timestamp in seconds that marks the beginning of the segment
insights (object):
- [insightName] (string object key): name of the user-created insight
  - array of objects
    - insight (string or object if insight has custom fields): the insight result
    - speaker (string or null): speaker the insight is associated with (if any)
    - timestamp (number or null): the timestamp in seconds the insight is associated with (if any)

Example

Getting started

Follow these steps to start receiving webhook events from Circleback:

Open Automations and add a webhook step to an existing or new automation.
Enter the webhook endpoint URL and toggle on what you don’t like to be included in webhook requests.
Select Done and Save the automation.

Requests

Once configured, you’ll start receiving POST requests at the provided endpoint URL with a JSON body that includes the following fields:

id (number): Circleback meeting ID
name (string): meeting name
createdAt (string): meeting creation date formatted in ISO string
duration (number): meeting duration in seconds
url (string or null): URL of the virtual meeting (i.e. Zoom, Google Meet, Microsoft Teams)
recordingUrl (string or null): URL of the meeting’s recording file which is only valid for 24 hours (only available if saving meeting recordings is enabled in settings)
attendees (array of objects): meeting attendees
- name (string or null): attendee name from calendar event if joined via calendar or from meeting if joined via link
- email (string or null): attendee email, only available if joined via calendar
notes (string): Circleback meeting notes with Markdown formatting
actionItems (array of objects): array of action items created for meeting
- id (number): Circleback action item ID
- title (string): action item title
- description (string): action item description
- assignee (object or null): action item assignee object or null if unassigned
  - name (string or null): assignee name
  - email (string or null): assignee email
- status (string): action item status, one of PENDING, IN_PROGRESS, DONE, or CANCELED
transcript (array of objects): meeting transcript segments
- speaker (string): speaker name
- text (string): words spoken
- timestamp (number): timestamp in seconds that marks the beginning of the segment
insights (object):
- [insightName] (string object key): name of the user-created insight
  - array of objects
    - insight (string or object if insight has custom fields): the insight result
    - speaker (string or null): speaker the insight is associated with (if any)
    - timestamp (number or null): the timestamp in seconds the insight is associated with (if any)

Example

{
  "id": 1234,
  "name": "Event Venue Review",
  "createdAt": "2023-07-25T20:30:57.926Z",
  "duration": 1306.09,
  "url": "https://meet.google.com/abc-defgh-xyz",
	"recordingUrl": null,
  "attendees": [
    { "name": "John Appleseed", "email": "john@example.com" },
    { "name": "Samantha Grey", "email": "sam@example.com" }
  ],
  "notes": "#### Overview\n*   Several options for event venues were reviewed...",
  "actionItems": [
    {
      "id": 252,
      "title": "Contact event venues",
      "description": "Reach out to Sunriver Events and other potential event venues to see if they would be open to hosting the event this summer.",
      "assignee": {
      	"name": "John Appleseed",
      	"email": "john@example.com"
      },
      "status": "PENDING"
    },
    {
      "id": 253,
      "title": "Review and finalize venue options",
      "description": "Review pricing and availability of venues and pick a venue for the event.",
      "assignee": null,
      "status": "PENDING"
    },
  ],
  "transcript": [
    {
	    "speaker": "John Appleseed",
	    "text": "Hey, how's it going?",
	    "timestamp": 4.56
    },
    {
	    "speaker": "Samantha Grey",
	    "text": "Going well, just testing webhooks in Circleback.",
	    "timestamp": 18.32
    }
  ],
  "insights": {
    "Customer details": [
	    {
		    "insight": {
			    "Company name": "Initech",
			    "Number of employees": 120
		    },
		    "speaker": "John Appleseed",
		    "timestamp": 800.00
	    }
    ],
    "Questions": [
			{
				"insight": "Is this thing on?",
				"speaker": "Samantha Grey",
				"timestamp": 49.15
			},
			{
				"insight": "When will the webhook integration be ready?",
				"speaker": "John Appleseed",
				"timestmap": 120.12
			}
    ]
  }
}

{
  "id": 1234,
  "name": "Event Venue Review",
  "createdAt": "2023-07-25T20:30:57.926Z",
  "duration": 1306.09,
  "url": "https://meet.google.com/abc-defgh-xyz",
	"recordingUrl": null,
  "attendees": [
    { "name": "John Appleseed", "email": "john@example.com" },
    { "name": "Samantha Grey", "email": "sam@example.com" }
  ],
  "notes": "#### Overview\n*   Several options for event venues were reviewed...",
  "actionItems": [
    {
      "id": 252,
      "title": "Contact event venues",
      "description": "Reach out to Sunriver Events and other potential event venues to see if they would be open to hosting the event this summer.",
      "assignee": {
      	"name": "John Appleseed",
      	"email": "john@example.com"
      },
      "status": "PENDING"
    },
    {
      "id": 253,
      "title": "Review and finalize venue options",
      "description": "Review pricing and availability of venues and pick a venue for the event.",
      "assignee": null,
      "status": "PENDING"
    },
  ],
  "transcript": [
    {
	    "speaker": "John Appleseed",
	    "text": "Hey, how's it going?",
	    "timestamp": 4.56
    },
    {
	    "speaker": "Samantha Grey",
	    "text": "Going well, just testing webhooks in Circleback.",
	    "timestamp": 18.32
    }
  ],
  "insights": {
    "Customer details": [
	    {
		    "insight": {
			    "Company name": "Initech",
			    "Number of employees": 120
		    },
		    "speaker": "John Appleseed",
		    "timestamp": 800.00
	    }
    ],
    "Questions": [
			{
				"insight": "Is this thing on?",
				"speaker": "Samantha Grey",
				"timestamp": 49.15
			},
			{
				"insight": "When will the webhook integration be ready?",
				"speaker": "John Appleseed",
				"timestmap": 120.12
			}
    ]
  }
}

Verifying incoming requests (optional)

To ensure the the webhook events received are from Circleback, you can choose to verify incoming requests using a signing secret. This is an optional step, but it is recommended for added security.

When you configure the webhook in an automation, you will be provided with a signing secret. This signing secret is a unique, secure string that is used to generate a cryptographic signature for each webhook event.

To verify the signature, you can follow these steps:

Extract the signature from the incoming request headers. The signature is in a header named x-signature.
Generate the expected signature using the signing secret and the request body.
Compare the expected signature with the provided signature. If they match, the request is considered valid and you can proceed to process the webhook event.

Here's an example implementation in TypeScript:

import crypto from 'crypto';

export const verifyWebhookSignature = (
  requestBody: string,
  signature: string, // 'X-Signature' header in the incoming request
  signingSecret: string  // Signing secret from Settings → Webhook (whsec_...)
): boolean => {
// Generate the expected signature
  const expectedSignature = crypto.createHmac('sha256', signingSecret)
    .update(requestBody)
    .digest('hex');

// Compare the expected signature with the provided signature
  return expectedSignature === signature;
};

// Example usage in a webhook endpoint handler
export const webhookEndpointHandler = async (req: express.Request, res: express.Response) => {
  try {
// Extract the necessary data from the request
    const { body: requestBody } = req;
    const signature = req.headers['x-signature'] as string;
    const signingSecret = 'your-signing-secret';

// Verify the signature
    if (!verifyWebhookSignature(JSON.stringify(requestBody), signature, signingSecret)) {
      return res.status(401).json({ error: 'Invalid signature.' });
    }

// Process the webhook event
    await processWebhookEvent(requestBody);

// Return a success response
    return res.status(200).json({ message: 'Webhook event processed successfully.' });
  } catch (error) {
    console.error('Error processing webhook event.', error);
    return res.status(500).json({ error: 'Error processing webhook event.' });
  }
};

Make sure to replace 'your-signing-secret' with the actual signing secret from the webhook automation step.

By verifying the signature, you can ensure that the webhook events you receive are from Circleback and have not been tampered with. This helps to protect your application from unauthorized access and potential attacks.

Circleback for desktop

Support

Security

Circleback for desktop

Circleback for desktop

Support

Security