Webhooks

Last updated Aug 28th, 2024

Webhooks
Webhooks

Overview

Webhooks enable you to send Contact, Organization, and Activity data to external services based on what's happening in Common Room. You can connect directly with services that support webhook triggers (like Zapier), or even build your own tools to consume and route your webhooks. For more information on which plans can purchase webhooks or have webhooks included in their plan, visit our pricing page.


Create a webhook

Create a webhook
Create a webhook

You can create a webhook from the Webhooks section of your Settings. When creating a webhook, you’ll fill in the following fields:

  • Webhook name - Use a descriptive name so you can easily distinguish between webhooks
  • Payload URL - The destination URL that will receive the payload of the webhook
  • Secret (optional) - An optional secret you can use to generate a signature for your webhook payload. This secret will be sent via the x-commonroom-webhook-secret header.

You can send test payloads to the Paylod URL directly from this page as well to confirm that the connection works as expected.

Webhook test results
Webhook test results

After creating, testing, and saving your webhook, you'll see it listed on the main webhook settings page.

Webhooks list
Webhooks list

Create webhook workflows

Once you have created your webhook, the next step is to set up workflows that will send data to the webhook based on whatever conditions you have. We currently offer four different workflow templates to get you up and running.

  • New member - This workflow will trigger anytime a new member is found in Common Room. This workflow will send the member payload to the specified webhook.
  • New organization - This workflow will trigger anytime a new organization is found in Common Room. This workflow will send the organization payload to the specified webhook.
  • New activity - This workflow will trigger anytime a new activity happens in Common Room. This workflow will send the activity payload to the specified webhook.
  • Members that meet criteria - This workflow will trigger once a day and send all members that meet the specified filter criteria to the webhook. After the initial run, the workflow will only run over new members that meet the criteria. This workflow will send the member payload to the specified webhook.

Once you have set any necessary criteria, enabling the workflow will begin sending out data to the specified webhook. We recommend that you test out your filters separately before enabling workflows as it can cause a large number of webhooks to be sent out.

Webhook payloads

We currently offer three different payload types via our webhooks. See below for sample payloads for each type.

Note that we do not consider additive fields to the payload as breaking changes. For renamed or deleted fields, we will notify you of changes.

Contact Payload

{
  "type": "contact",
  "version": "202304",
  "avatarUrl": "https://www.example.com/avatar/1d387064a52ba82a.png",
  "segments": [
    {
      "id": 72602171,
      "name": "Test Segment"
    }
  ],
  "tags": [
    {
      "id": 70790368,
      "name": "Test Tag"
    }
  ],
  "title": "Technical Writer",
  "role": "Technical Communications",
  "firstSeenDate": "2023-04-17T10:21:26.978Z",
  "firstSeenSignal": "YouTube",
  "lastSeenDate": "2023-04-17T10:21:26.978Z",
  "lastSeenSource": "LinkedIn",
  "fullName": "Marion Sanford",
  "primaryEmail": "marionsanford@example.com",
  "organization": {
    "name": "TechWrite Solutions",
    "domain": "techwritesolutions.com",
    "location": {
      "city": "Austin",
      "region": "Texas",
      "country": "USA"
    }
  },
  "allEmails": ["marionsanford@example.com"],
  "linkedIn": "in/msanford",
  "twitter": "msanford",
  "github": "msanford",
  "discord": "msanford#1234",
  "youtube": "msanford",
  "linkedInUrl": "https://linkedin.com/in/msanford",
  "twitterUrl": "https://twitter.com/i/user/12345678",
  "githubUrl": "https://github.com/msanford",
  "discordUrl": "https://discord.com/users/msanford#12345678",
  "youtubeUrl": "https://www.youtube.com/channel/msanford"
}

Organization payload

{
  "type": "organization",
  "version": "202304",
  "name": "TechWrite Solutions",
  "domain": "techwritesolutions.com",
  "location": {
    "city": "Austin",
    "region": "Texas",
    "country": "USA"
  },
  "logoUrl": "https://www.example.com/logo/1d387064a52ba82a.png"
}

Activity payload

{
  "type": "activity",
  "version": "202304",
  "contact": {
    "primaryEmail": "marionsanford@example.com",
    "organization": {
      "name": "TechWrite Solutions",
      "domain": "techwritesolutions.com",
      "location": {
        "city": "Austin",
        "region": "Texas",
        "country": "USA"
      }
    },
    "fullName": "Marion Sanford",
    "allEmails": ["marionsanford@example.com"],
    "linkedIn": "in/msanford",
    "twitter": "msanford",
    "github": "msanford",
    "discord": "msanford#1234",
    "youtube": "msanford",
    "linkedInUrl": "https://linkedin.com/in/msanford",
    "twitterUrl": "https://twitter.com/i/user/12345678",
    "githubUrl": "https://github.com/msanford",
    "discordUrl": "https://discord.com/users/msanford#12345678",
    "youtubeUrl": "https://www.youtube.com/channel/msanford"
  },
  "activityType": "DiscordThreadCreated",
  "serviceName": "Discord",
  "title": "Title of parent thread",
  "content": "New Thread Name",
  "commonRoomActivityUrl": "https://app.commonroom.io/community/123/activity/eyJwcm92aWRlcklkIjoxMjM0LCJ0b2tlbiI6ImRtXzEyMzQ1NjcifQ==",
  "externalActivityUrl": "https://discord.com/channels/12345/67890/threads/98765",
  "timestamp": "2023-04-17T10:21:26.978Z",
  "categories": ["Product Question"],
  "sentiment": "Positive",
  "tags": ["Test Tag"],
  "topics": ["api","documentation"]
}

Didn't find your answer?Get in touch· Visit ourhelp center