Webhooks are a type of alert destination. For more information, please refer to the “Alerts and Destinations” guide.
🚧 Beta Feature
Webhooks are currently in beta and subject to change. Please refer to this guide for the latest changes. Join our beta program for access.
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.
Right now, the following events are supported:
On HTTP requests, Orbit includes the following HTTP headers:
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": "1",
"event_type": "activity:created",
"event_payload": {
"data": {
"id": "5159390",
"type": "star_activity",
"attributes": {
"action": "created",
"created_at": "2020-12-21T19:45:54.233Z",
"key": "orbit-love/orbit-model@2020-12-21T19:45:53Z",
"occurred_at": "2020-12-21T19:45:53.000Z",
"updated_at": "2021-01-08T19:25:23.582Z",
"type": "StarActivity",
"tags": [
"channel:github",
"github_organization:orbit-love",
"github_repository:orbit-love/orbit-model"
],
"orbit_url": "https://app.orbit.love/orbit/activities/5159390",
"activity_link": "https://github.com/orbit-love/orbit-model",
"g_starred_at": "2020-12-21T19:45:53Z"
},
"relationships": {
"activity_type": {
"data": {
"id": "3",
"type": "activity_type"
}
},
"member": {
"data": {
"id": "957993",
"type": "member"
}
},
"repository": {
"data": {
"id": "2650",
"type": "repository"
}
}
}
}
}
}
{% c-block-end %}
Event payload data format reflects the current properties from the Orbit API. Please refer to the API documentation for more information.
To be considered a successful alert delivery, your webhook application must meet the following criteria:
Any HTTP request that does not meet the requirements will count as a failure towards interoperability. For more information on destination interoperability, please refer to the “Alerts and Destinations” guide.
Orbit will attempt an alert delivery three times before flagging the destination as inoperable. Retry failures will be attempted with an exponential backoff. This will roughly translate to about 3 minutes total waiting time before a destination hits the max retries.
After the final failure, the destination will be disabled. This will not impact other enabled destinations that belong to the same alert. Once you’ve addressed the issue in your application, you can manually re-enable the destination to try again.
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.
We recommend using a randomly generated string of at least 20 characters.
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 alert, please refer to the "Alerts and Destinations" guide.
Webhooks are currently in beta. We would love to hear more about your workflow. Please feel free to reach out with any feedback on the feature.