Configuring your Source system with webhooks

Once your webhook definition is created in Faros, you can configure your source system. Each webhook definition provides a unique URL to send data to, with the following structure:


Modify :webhook_id with the correct id from your webhook definition (API reference)



Please refer to the documentation of the source system to learn best practices on how to set up webhooks for it.

Configuring a GitHub webhook

Please refer to GitHub documentation for full details.

GitHub webhooks can be set up to send GitHub events to Faros either at the repository or the organization level:

  • Repository level: sends events for that repository only. You need to have Admin permission.
  • Organization level: sends events for all repositories and members. You need to be an Owner for the organization to configure these.

To configure a webhook for either a repository or an organization, go to the repository or organization main page, select Settings from the top-level menu, then select Webhooks under Code and Automation.

Repository Settings

Setup the webhook

  • Input the as the payload URL. Modify :webhook_id with the correct id from your webhook definition.
  • Select Content type to be application/json.
  • (Recommended) If you provided a secret when creating a Faros webhook definition, supply the same value here. You can read more how GitHub secures your webhook using the secret here.
  • Choose what GitHub events to send to Faros. Select Let me select individual events and select:
    • Branch or tag creation
    • Branch or tag deletion
    • Pull request review comments
    • Pull request reviews
    • Pull requests
    • Pushes
    • Repositories
    • Organizations (event that can only be configured when setting a webhook for an Organization)


To send these events the GitHub user must have at least read-level access permissions for:

  • Contents - repository
  • Members - organization
  • Pull requests - repository
  • Metadata - repository

After successfully adding the webhook, it will appear in the list of webhooks configured for the repository or organization. Select the webhook to view its details to ensure it is correctly set up. At the bottom of the page, there should be a section Recent Deliveries showing that it successfully sent a "ping" event to your Faros webhook.