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.

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:

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": "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.

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. For more information on destination interoperability, please refer to the “Alerts and Destinations” guide.

Retries

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.

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.

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 alert, please refer to the "Alerts and Destinations" guide.

Feedback

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.