Orbit API
Webhooks
Available on Starter, Growth, Premium & Enterprise plans
Available on Growth, Premium & Enterprise plans
Available on Premium & Enterprise plans
Available on the Enterprise plan
Outbound webhooks are available via Automations. This guide serves as an in depth guide on the Webhook action specifically.
Overview
Webhooks allow you to build tighter integrations with Orbit. When an event occurs in your workspace, we will send an event payload to your application URL. The mechanism for webhooks is an HTTP POST request with a JSON format.
Events
Right now, the following events are supported:
Headers
On HTTP requests, Orbit includes the following HTTP headers:
- X-Orbit-Signature
- X-Orbit-Event-Type
- X-Orbit-Event-ID
- X-Orbit-Event
Payload
The request body is JSON, so your application must accept the application/json. On every request body, Orbit includes the following keys:
{% c-block language="json" %}
{
"event_id": "rkKu5P",
"event_type": "activity:created",
"event_payload": {
"data": {
...
}
}
}
{% c-block-end %}
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 below:
Activity Payload
{% c-block language="json" %}
{
"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"
}
}
]
}
}
{% c-block-end %}
New Member Payload
{% c-block language="json" %}
{
"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": []
}
}
}
}
}
{% c-block-end %}
Note: 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.
New Note Payload
{% c-block language="json" %}
{
"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"
}
}
}
}
}
}
{% c-block-end %}
Requirements
To be considered a successful alert delivery, your webhook application must meet the following criteria:
- Accept HTTP POST requests
- Accept application/json
- Return 200 OK HTTP status code
- Respond within 5 second timeout
Any HTTP request that does not meet the requirements will count as a failure towards interoperability.
Retries
Orbit will attempt a webhook delivery three times before flagging the whole automation as inoperable. Retry failures will be attempted with an exponential backoff. This will roughly translate to about 3 minutes total waiting time before an automation hits the max retries.
After the final failure, the automation will be disabled. Once you’ve addressed the issue in your application, you can manually re-enable the automation to try again.
Securing
When you create a webhook destination, you have the option of providing a secret token to be used for verifying signatures from Orbit. When a secret token is provided, Orbit will use the secret token 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.
Testing
Right now, we do not support webhook testing in the UI. A workaround would be to manually create an activity in the UI to trigger an alert delivery. For more information on creating an automation that uses webhooks, please refer to the Automations guide.
