📙

Webhooks

Documentation

‣
Getting Started
📙
What is Orbit?
📙
Understanding the Orbit Model
📙
Orbit Glossary
‣
Workspaces
📙
Create an Orbit workspace
📙
Invite a teammate
📙
Enable SSO (Single Sign-On)
📙
Demo mode
‣
Members
📙
Intro to members
📙
View an individual member
📙
Preview a member
📙
Explore members via the members tab
📙
Add a member
📙
Edit a member
📙
Merge duplicate members
📙
Delete a member
📙
Add a tag to a member
📙
Add, edit, and delete notes on a member
📙
Add an activity to a member
📙
Mark profile as a teammate
📙
Send member to a webhook
‣
Activities
📙
Create an activity type
📙
Intro to activities
‣
Organizations
📙
Intro to organizations
📙
View an individual organization
📙
Identify an organization as a customer
‣
Reports
📙
Create a custom dashboard
📙
Drill down into reports
📙
Quickly build an activities chart
📙
Understanding sentiment analysis
‣
Automations
📙
Automations [deprecated]
📙
Webhooks
📙
Set up a manual webhook
📙
Workflows
📙
Slack notifications
📙
Set up an automated webhook
‣
Productivity
📙
Member lists
📙
Tags
📙
Manage tags
📙
Create a saved view
📙
Share a saved view
📙
CSV import for members and activities
📙
Using filters on the members tab
📙
Using filters on the activities and reports tabs
📙
Keyboard shortcuts
📙
Search
‣
Integrations
📙
All possible data integrations with Orbit
📙
DEV integration
📙
Discord integration
📙
Discourse integration
📙
GitHub integration
📙
HubSpot integration
📙
inSided integration
📙
LinkedIn integration
📙
Reddit integration
📙
Salesforce integration
📙
Slack integration
📙
Stack Overflow integration
📙
Twitter integration
📙
Twitter keywords integration
📙
YouTube integration
📙
Zapier integration
📙
Twitter DMs integration
‣
Tools
📙
Stripe Dashboard application
📙
GitHub Chrome extension
📙
Slack App
📙
Orbit API
📙
API tokens
‣
FAQ
📙
How are historic Discord imports handled after initial set up?
📙
How can I filter members to only see those with notes added?
📙
How does member enrichment work?
📙
Is test data available to try in Orbit?
📙
What activities are tracked by each integration?
📙
What can I do if I imported a CSV with incorrect column headers?
📙
What's the difference between Activities and Tags?
📙
Why am I no longer designated as a teammate?
📙
Why are there differences between member counts on Orbit and Discord?
📙
Why can't I see the Plug & Play integrations?
📙
Why is my CSV file not importing?
📙
Will uninstalling an integration remove activities from Orbit?
📙
How is the new members table different from the old members table?

Webhooks

Webhooks allow you to build tighter integrations with Orbit and external services via their APIs. You can use webhooks for just about anything and choose whether they are automated, or manually triggered.

To get started using webhooks in Orbit, head to the Settings section of your workspace and click on Webhooks.

image

Types of Webhooks

We have two types of webhooks available. Automated, and manually triggered.

Automated

Automated webhooks allow you to set certain trigger criteria, such as specific events, new members, or note additions. Each time Orbit matches the criteria you set, we will send either Member or Activity payload to the associated webhook.

More about how to set up an automated webhook

Manual

Manually triggered webhooks allow you to build your own actions and integrations that can be triggered directly by you from a Member profile.

More about how to manually trigger a webhook

Request Type

The mechanism for webhooks is an HTTP POST request and the payloads we send are formatted as JSON.

Headers

On HTTP requests, Orbit includes the following HTTP headers:

  • X-Orbit-Signature
  • X-Orbit-Event-Type
  • X-Orbit-Event-ID
  • X-Orbit-Event

Request Body

The request body is JSON, so your application must accept the application/json content type.

On every request body, Orbit prepends the following additional keys to give you some more context about the reason the webhook was triggered, and to allow you to differentiate between different requests to the same webhook URL:

{
  "event_id": "rkKu5P",
  "event_type": "activity:created",
  "event_payload": {
    "data": {
      ...
    }
  }
}

The content of the data object will differ depending on the event type and reflects the current properties from the Orbit API.

Please refer to the API documentation for more information. Examples of what you can expect can also be found in the Payload Examples section below.

Acceptance Requirements

To ensure successful delivery, the application or service you are sending the webhook to must meet the following criteria:

  • Accept HTTP POST requests
  • Accept application/json content type
  • Return 200 OK HTTP status code
  • Respond within the 5 second timeout window

Any HTTP request that does not meet the requirements will fail, and then be retried.

Retries

Orbit will attempt a webhook delivery three times before flagging it as Failed. Retry failures will be attempted with an exponential backoff. This roughly translates to about 3 minutes total waiting time before an automation hits the max retries.

After the final failure, an automated webhook will be disabled. Once you’ve addressed the issue in your application, you can manually re-enable the automation to try again from the Webhooks section of your workspace Settings.

Securing your webhooks

When you create a webhook destination, you have the option of providing a secret token to be used for verifying that the requests being sent your application from Orbit, are actually coming from Orbit. It’s good practice to implement this if you can.

image

When a secret token is provided, Orbit will use it as a HMAC-SHA256 key and generate an HMAC hex digest of the HTTP request body. This will be passed in the x-orbit-signature header of the HTTP request.

We recommend using a randomly generated string of at least 20 characters.

Your application will need to decrypt this signature in order to check the validity of the requests you are receiving.

Payload Examples

Activity Payload

This payload will be sent for any Automated webhook that uses a specific activity type as the trigger.

{
  "event_id": "rkKu5P",
  "event_type": "activity:created",
  "event_payload": {
    "data": {
      "id": "2zs410",
      "type": "custom_activity",
      "attributes": {
        "key": "HKo6WTidCXuEbGyc",
        "tags": [
          "channel:product",
          "custom_type:account:activated",
          "custom_title:joined-orbit"
        ],
        "type": "CustomActivity",
        "action": "happened",
        "weight": "1.0",
        "orbit_url": "http://app.orbit.love/workspaceslug/memberslug",
        "created_at": "2022-06-20T17:04:42.515Z",
        "properties": {},
        "updated_at": "2022-06-20T17:04:42.515Z",
        "custom_link": "",
        "custom_type": "account:activated",
        "occurred_at": "2022-06-20T17:04:42.510Z",
        "custom_title": "Joined Orbit",
        "custom_context": null,
        "custom_link_text": "",
        "custom_description": ""
      },
      "relationships": {
        "user": {
          "data": {
            "id": "l9YF2l",
            "type": "user"
          }
        },
        "member": {
          "data": {
            "id": "8eSxny",
            "type": "member"
          }
        },
        "activity_type": {
          "data": {
            "id": "5mwsRl",
            "type": "activity_type"
          }
        }
      }
    },
    "included": [
      {
        "id": "5mwsRl",
        "type": "activity_type",
        "attributes": {
          "key": "account:activated",
          "name": "Activated their account",
          "source": "product",
          "weight": "1.0",
          "channel": "product",
          "short_name": "Activated account"
        }
      },

      {
        "id": "j6TdN8",
        "type": "github_identity",
        "attributes": {
          "uid": null,
          "name": null,
          "email": null,
          "source": "github",
          "username": "githubusername",
          "source_host": "github.com"
        }
      },

      {
        "id": "yVTre8",
        "type": "twitter_identity",
        "attributes": {
          "uid": "14761655",
          "name": "Firstname Lastname",
          "email": null,
          "source": "twitter",
          "username": "twitterusername",
          "source_host": "twitter.com"
        }
      },
      {
        "id": "8eSxny",
        "type": "member",
        "attributes": {
          "id": "8eSxny",
          "bio": "The member bio would be here",
          "url": "https://thememberwebsite.com/wouldbehere",
          "love": null,
          "name": "Firstname Lastname",
          "slug": "",
          "tags": [],
          "devto": null,
          "email": null,
          "reach": 10,
          "title": null,
          "github": "theusersgithubusername",
          "source": "web",
          "topics": null,
          "tshirt": null,
          "company": null,
          "created": false,
          "discord": null,
          "twitter": "theuserstwitterusername",
          "birthday": null,
          "linkedin": null,
          "location": "Big Town, MA",
          "pronouns": null,
          "tag_list": [],
          "teammate": false,
          "discourse": null,
          "languages": null,
          "merged_at": null,
          "orbit_url": "http://app.orbit.love/workspaceslug/memberslug",
          "avatar_url": "https://pbs.twimg.com/profile_images/1372299372052/KHLARcj.jpg",
          "created_at": "2022-06-20T17:02:30.230Z",
          "deleted_at": null,
          "updated_at": "2022-06-20T17:02:30.837Z",
          "orbit_level": null,
          "activities_count": 0,
          "activities_score": 0,
          "github_followers": null,
          "shipping_address": null,
          "twitter_followers": 62554,
          "last_activity_occurred_at": null,
          "first_activity_occurred_at": null
        },
        "relationships": {
          "identities": {
            "data": [
              {
                "id": "j6TdN8",
                "type": "github_identity"
              },
              {
                "id": "yVTre8",
                "type": "twitter_identity"
              }
            ]
          }
        }
      },
      {
        "id": "l9YF2l",
        "type": "user",
        "attributes": {
          "name": "Firstname Lastname",
          "created_at": "2021-11-08T21:08:10.779Z",
          "updated_at": "2022-06-20T17:00:59.633Z"
        }
      }
    ]
  }
}

Member Payload

This payload will be sent for any Automated webhooks that use the New Member Created trigger, as well as for any manually triggered webhooks.

{
  "event_id": "E1AulK",
  "event_type": "member:created",
  "event_payload": {
    "data": {
      "id": "8eSxny",
      "type": "member",
      "attributes": {
        "id": "8eSxny",
        "bio": null,
        "url": null,
        "love": null,
        "name": "Firstname Lastname",
        "slug": "firstnamelastname",
        "tags": [],
        "devto": null,
        "email": null,
        "reach": null,
        "title": null,
        "github": null,
        "source": "web",
        "topics": null,
        "tshirt": null,
        "company": null,
        "created": null,
        "discord": null,
        "twitter": null,
        "birthday": null,
        "linkedin": null,
        "location": null,
        "pronouns": null,
        "tag_list": [],
        "teammate": false,
        "discourse": null,
        "languages": null,
        "merged_at": null,
        "orbit_url": "https://app.orbit.love/workspaceslug/memberslug",
        "avatar_url": null,
        "created_at": "2022-06-20T17:02:30.230Z",
        "deleted_at": null,
        "updated_at": "2022-06-20T17:02:30.230Z",
        "orbit_level": null,
        "activities_count": 0,
        "activities_score": 0,
        "github_followers": null,
        "shipping_address": null,
        "twitter_followers": null,
        "last_activity_occurred_at": null,
        "first_activity_occurred_at": null
      },
      "relationships": {
        "identities": {
          "data": []
        }
      }
    }
  }
}
💡
When using an Automated Webhook, the Member payload can be triggered before any enrichment of the profile has completed. This means that certain fields may be unpopulated at the time of the trigger that will later appear populated on the member profile and in API requests.

New Note Payload

This payload will be sent when using the New Note trigger on an Automated Webhook.

{
  "event_id": "N0VuvO",
  "event_type": "note:created",
  "event_payload": {
    "data": {
      "id": "JegfGz",
      "type": "note",
      "attributes": {
        "id": "JegfGz",
        "body": "Had a great call with about upcoming conference schedule.",
        "created_at": "2022-06-20T17:05:13.626Z",
        "updated_at": "2022-06-20T17:05:13.626Z"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "l9YF2l",
            "type": "user"
          }
        },
        "member": {
          "data": {
            "id": "8eSxny",
            "type": "member"
          }
        }
      }
    }
  }
}

Testing

Right now, we do not support webhook testing in the UI. A workaround for automated webhooks would be to manually create an activity in the UI to trigger the webhook.

Manual trigger webhooks can be tested by triggering them as you would normally from the UI.

Resources

You can access webhooks from a few different places in Orbit: a member’s profile, the Members Tab, and workflows (soon!). To learn more about how to use workflows in these various locations, manually and automatically, here are some resources:

We also have some guides that show how you can take advantage of webhooks in Orbit:

External Resources

Learn how to integrate your local app with Orbit Webhooks with this great guide from the ngrok team.

DiscordTwitterGitHubLinkedIn