Whenever an event is triggered, DeepSource sends a POST request to a URL configured by you. These events are usually specific points that happen during certain actions like Analysis, Autofix, billing, team updates etc. You can use this to update an external issue tracker, to notify about check results on Slack or Telegram, and much more.

Note

Webhooks can be enabled for organization accounts only.

Begin using webhooks with your DeepSource account in just three steps:

  • Create a webhook endpoint for your integration.
  • Use the DeepSource dashboard to add that endpoint to your organization.
  • Sip coffee while we send events to your configured URL.

You can find the list of all available events here.

​
Creating an endpoint

To create an endpoint, go to your team settings from your sidebar and navigate to the Webhooks tab. If this is your first time using Webhooks, click ‘Add a new endpoint’.

There are three options to configure:

  1. Endpoint URL: This has to be a public-facing endpoint that accepts a POST request. The payload will be sent to this endpoint whenever an event is triggered.
  2. Enable API signing: This will send an HMAC signature of the payload, created using the secret configured by you. Enabling this will allow you to verify if the request was indeed sent by DeepSource. We recommend enabling this.
  3. Webhook secret: Secret for API signing mentioned above. This needs to be at least 16 characters.

Once you fill in these details, you will have to select at least one event. You can find the list of all available events here.

Once created, the webhook configuration will be saved, but webhooks will be activated only after verification of the test payload

​
Enabling an endpoint

To enable an endpoint you will have to verify the endpoint by sending a test event.

Once we receive a 2XX response from the endpoint, the webhook will be activated.

​
Testing an endpoint

After activation, you can test your endpoint whenever you want by sending a test payload. The test payload is the same one used for activation.

​
Verifying the payload

If API signing is enabled, every request will have a x-deepsource-signature header. This signature is generated by hashing the payload with the secret provided by you. It can be used to verify the authenticity of the payload. HMAC is widely supported across programming languages and frameworks, here are a few implementations to get you started.

​
Events

Each webhook event is structured as follows:

  • id: A unique id to identify this webhook event delivery.
  • type: The triggered webhook event’s shortcode.
  • createdAt: A UNIX timestamp of when this event was created.
  • data.object: The object associated with the webhook event. For e.g., in the case of analysis_run.updated webhook event, data.object is an AnalysisRun object.
  • Other than data.object there can be additional fields depending on the webhook event.

​
Analysis Run Started

This event is triggered every time an analysis run is triggered. Since this event is triggered each time an analysis run starts, expect the summary attribute to be empty.

Event shortcode: analysis_run.started

data.object is an AnalysisRun.

​
Sample Payload

​
Analysis Run Updated

This event is triggered every time one of the configured analyzer returns a result for a particular run. For a single run, since any number of analyzers can be configured, there will be multiple events triggered: one per analyzer/check.

All the past checks associated with this run will also be present in the payload (checks). The last check in the list is the check that triggered this event.

Event shortcode: analysis_run.updated

data.object is an AnalysisRun.

​
Sample Payload

​
Autofix Run Started

This event is triggered when a new Autofix is created.

Event shortcode: autofix_run.started

data.object is an AutofixRun.

​
Sample Payload

​
Autofix Run Updated

This event is triggered when the status or corresponding PR of an Autofix is updated.

Event shortcode: autofix_run.updated

data.object is an AutofixRun.

​
Sample Payload

​
Repository Analysis Activated

This event is triggered when an analysis is activated on a repository.

Event shortcode: repository.analysis.activated

data.object is a Repository.

​
Sample Payload

​
Repository Analysis Deactivated

Event shortcode: repository.analysis.deactivated

data.object is a Repository.

This event is triggered when analysis is deactivated on a repository.

​
Sample Payload

​
Repository Issue Introduced

Event shortcode: repository_issue.introduced

data.object is a RepositoryIssue.

data.issueOccurrencesIntroduced is the total count of issue occurrences introduced in the commit.

This event is triggered whenever an issue has been detected in the default branch of the repository.

For instance, if 3 occurrences of issue X and 5 occurrences of issue Y are introduced in the default branch after a commit, two events, one for each issue will be triggered.

This event is not triggered for full runs on the default branch. A full run is when your repository’s full code base is analyzed. This happens, e.g., when the repository is (re)activated, or if the .deepsource.toml gets updated. This is to prevent noise which can arise from a large number of issues being reported in such runs.

​
Sample Payload

​
Repository Issue Resolved

This event is triggered whenever an issue is resolved in the default branch of the repository.

For instance, if 3 occurrences of issue X and 5 occurrences of issue Y are resolved in the default branch after a commit, two events, one for each issue, will be triggered.

This event is not triggered for full runs on the default branch. A full run is when your repository’s full code base is analyzed. This happens, e.g., when the repository is (re)activated or if the .deepsource.toml gets updated. This is to prevent noise that can arise from a large number of issues being reported in such runs.

Event shortcode: repository_issue.resolved

data.object is a RepositoryIssue.`

data.issueOccurrencesResolved is the total count of issue occurrences resolved in the commit.

data.object.occurrences will always be an empty list.

​
Sample Payload

​
Team Member Added

This event is triggered when a new member is added to a team.

Event shortcode: team_member.added

data.object is a TeamMember.

​
Sample Payload

​
Team Member Removed

Event shortcode: team_member.removed

data.object is a TeamMember.

This event is triggered when a team member is removed.

​
Sample Payload

​
Team Member Role Updated

This event is triggered when the role of a team member is changed.

Event shortcode: team_member.updated

data.object is a TeamMember.

data.oldRole is the user’s old role in the team.

data.newRole is the user’s new role in the team.

​
Sample Payload

​
Test

This event does not correspond to any activity on DeepSource. It is used exclusively for testing and verification of your endpoint.

Event shortcode: test.event

​
Sample Payload

Command Line Interface (CLI)Overview