Webhooks | Common Room (Docs)

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

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 include in your webhook payloads. This secret will be sent via the x-commonroom-webhook-secret header.

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

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 contact - This workflow will trigger anytime a new contact is found in Common Room. This workflow will send the contact 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.
Contacts that meet criteria - This workflow will trigger once a day and send all contacts that meet the specified filter criteria to the webhook. After the initial run, the workflow will only run over new contacts that meet the criteria. This workflow will send the contact payload to the specified webhook.
Anonymous website visit - This workflow will trigger anytime there is an anonymous visitor from an organization that visits your website. This workflow will send an organization payload to the specified webhook.
Contact identified from website visit - This workflow will trigger anytime there is an identified contact that visits your website. This workflow will send a contact 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

{
  "payload": {
    "primaryEmail": "marionsanford@domain1.com",
    "organization": {
      "name": "TechWrite Solutions",
      "domain": "techwritesolutions.com",
      "location": {
        "city": "Austin",
        "region": "Texas",
        "country": "USA"
      }
    },
    "previousOrganization": {
      "name": "DataFlow Systems",
      "domain": "dataflowsystems.com"
    },
    "previousTitle": "Senior Technical Writer",
    "organizationChangeDate": "2023-06-15T00:00:00.000Z",
    "fullName": "Marion Sanford",
    "allEmails": [
      "marionsanford@domain1.com",
      "marionsanford@domain2.com",
      "marionsanford@domain3.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",
    "type": "member",
    "version": "202304",
    "avatarUrl": "https://www.example.com/avatar/1d387064a52ba82a.png",
    "commonRoomContactLink": "https://app.commonroom.io/community/123/member/456",
    "city": "Austin",
    "country": "USA",
    "region": "Texas",
    "firstActivityDate": "2002-11-19T06:45:59.888Z",
    "firstActivitySource": "YouTube",
    "firstSeenDate": "2002-11-19T06:45:59.888Z",
    "firstSeenSource": "YouTube",
    "firstSeenWebVisitDate": "2002-11-19T06:45:59.888Z",
    "firstSeenWebVisitUrl": "https://www.example.com/first-visit",
    "lastActivityDate": "2022-12-05T00:27:54.679Z",
    "lastActivitySource": "LinkedIn",
    "lastSeenDate": "2022-12-05T00:27:54.679Z",
    "lastSeenSource": "LinkedIn",
    "lastSeenWebVisitDate": "2022-12-05T00:27:54.679Z",
    "lastSeenWebVisitUrl": "https://www.example.com/last-visit",
    "phoneNumbers": [
      "+1-555-123-4567"
    ],
    "professionalEmail": "marion.sanford@techwritesolutions.com",
    "segments": [
      {
        "id": 72602171,
        "name": "Test Segment"
      }
    ],
    "tags": [
      {
        "id": 70790368,
        "name": "Test Tag"
      }
    ],
    "title": "Technical Writer",
    "role": "Technical Communications"
  },
  "id": "44a25438-c743-47cd-9e12-690a456c6988",
  "source": {
    "type": "workflow",
    "id": 1234,
    "name": "Test Workflow"
  }
}

Organization payload

{
  "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",
    "description": "This is the company's description",
    "industry": "Aerospace",
    "technologies": [
      "TypeScript",
      "React",
      "Node.js"
    ],
    "commonRoomOrgLink": "https://app.commonroom.io/community/123/organization/456",
    "employeeCount": 50,
    "firstActivityDate": "2022-01-15T10:30:00.000Z",
    "firstActivitySource": "LinkedIn",
    "firstSeenWebVisitDate": "2022-01-15T10:30:00.000Z",
    "firstSeenWebVisitUrl": "https://www.example.com/first-org-visit",
    "lastActivityDate": "2023-12-01T15:45:00.000Z",
    "lastActivitySource": "GitHub",
    "lastSeenWebVisitDate": "2023-12-01T15:45:00.000Z",
    "lastSeenWebVisitUrl": "https://www.example.com/last-org-visit",
    "revenueRangeMax": 10000000,
    "revenueRangeMin": 1000000
  },
  "id": "1919a6ec-7a67-4653-858a-e58306960753",
  "source": {
    "type": "workflow",
    "id": 1234,
    "name": "Test Workflow"
  }
}

Activity payload

{
  "payload": {
    "type": "activity",
    "version": "202506",
    "member": {
      "primaryEmail": "marionsanford@domain1.com",
      "organization": {
        "name": "TechWrite Solutions",
        "domain": "techwritesolutions.com",
        "location": {
          "city": "Austin",
          "region": "Texas",
          "country": "USA"
        }
      },
      "fullName": "Marion Sanford",
      "allEmails": [
        "marionsanford@domain1.com",
        "marionsanford@domain2.com",
        "marionsanford@domain3.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": "Thread Title",
    "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"
    ],
    "company": {
      "name": "TechWrite Solutions",
      "domain": "techwritesolutions.com",
      "location": {
        "city": "Austin",
        "region": "Texas",
        "country": "USA"
      },
      "logoUrl": "https://www.example.com/logo/1d387064a52ba82a.png",
      "description": "This is the company's description",
      "industry": "Aerospace",
      "technologies": [
        "TypeScript",
        "React",
        "Node.js"
      ],
      "commonRoomOrgLink": "https://app.commonroom.io/community/123/organization/456",
      "employeeCount": 50,
      "firstActivityDate": "2022-01-15T10:30:00.000Z",
      "firstActivitySource": "LinkedIn",
      "firstSeenWebVisitDate": "2022-01-15T10:30:00.000Z",
      "firstSeenWebVisitUrl": "https://www.example.com/first-org-visit",
      "lastActivityDate": "2023-12-01T15:45:00.000Z",
      "lastActivitySource": "GitHub",
      "lastSeenWebVisitDate": "2023-12-01T15:45:00.000Z",
      "lastSeenWebVisitUrl": "https://www.example.com/last-org-visit",
      "revenueRangeMax": 10000000,
      "revenueRangeMin": 1000000
    }
  },
  "id": "b1bee316-b482-40fa-9175-5d149a5d231c",
  "source": {
    "type": "workflow",
    "id": 1234,
    "name": "Test Workflow"
  }
}