Documentation
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.
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.
Manual
Manually triggered webhooks allow you to build your own actions and integrations that can be triggered directly by you from a Member profile.
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.

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": []
}
}
}
}
}
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.