Webhooks

Screenshotbot provides a mechanism to get notifications of events via webhooks. Webhooks are nothing but HTTP callbacks that are called from Screenshotbot to a service you own and operate.

Setting up webhooks

To set up webhooks, go to Settings -> Webhooks. Provide a Webhook endpoint, and check the Enable webhooks checkbox.

You can click the Show Signing Key to get the signing key Screenshotbot will use to sign every request. By verifying the signature of every payload, you can be sure that it was generated by us.

Secure your webhooks (recommended)

Screenshotbot sends a POST request to your service with the given payload. The payload is a JSON body, which we will describe in the next section.

Before you parse the JSON body, you might want to verify the payload. (You can skip this step if you're not doing anything sensitive with the event.)

Each request will have a header Screenshotbot-Signature that looks like t=%d,signature=%s. t is the unix timestamp in UTC when the payload was created. signature is HMAC-SHA256 of {t}.{payload}, using the signing key from the settings page.

To prevent replay attacks, you might want to verify that the timestamp in the signature was less than, say, five minutes in the past.

Debugging and Testing Webhooks

While building a service that listens to webhooks, you might have to test and debug the integration.

We provide a log of all the webhooks we have sent out in the last 30 days, and give you a way to inspect the payload that was sent, and also an option to resend failed payloads.

This let's you test your endpoint without having to manually reproduce the event in Screenshotbot each time.

Webhook events

Event channel.promotion

This event is dispatched when a promotion happens on a branch that resulted in a report.

This event has the following fields:

channel

The channel name on which this promotion happened.

branch

The git branch on which this promotion happened. e.g. `main`

run

The run that triggered this event

Expand contents

id

The ID of this run

channel

The channel name used with this run

screenshots

A list of screenshots for this run. This field may not be present when querying a run.

Expand contents

name

The name associated with this screenshot

imageId

The ID of the image associated with this screenshot

commit

The Git commit hash for this run

pullRequestUrl

The pull request URL associated with this run, if any.

mainBranchCommit

The Git hash of the main branch at the time that this run was created.

overrideCommitHash

The Git hash associated with the current run. This might be different from `commit` if the CI job had a step of rebasing the changes onto the master branch.

buildUrl

The URL of the build job that created this run

mergeBase

The commit hash of the merge base of this commit with the main branch.

mainBranch

The main branch, usually `main` or `master`.

workBranch

The branch on which the CI job was run

phabricatorDiff

A Phabricator Diff ID associated with the run, if any.

gitlabMergeRequestIID

A GitLab merge request IID associated with the run, if any.

repo

The repository URL

compareThreshold

The comparison threshold used for comparisons associated with this run.

url

The URL of this run

batch

The batch name associated with this run

previousRun

The previous promoted run

Expand contents

id

The ID of this run

channel

The channel name used with this run

screenshots

A list of screenshots for this run. This field may not be present when querying a run.

Expand contents

name

The name associated with this screenshot

imageId

The ID of the image associated with this screenshot

commit

The Git commit hash for this run

pullRequestUrl

The pull request URL associated with this run, if any.

mainBranchCommit

The Git hash of the main branch at the time that this run was created.

overrideCommitHash

The Git hash associated with the current run. This might be different from `commit` if the CI job had a step of rebasing the changes onto the master branch.

buildUrl

The URL of the build job that created this run

mergeBase

The commit hash of the merge base of this commit with the main branch.

mainBranch

The main branch, usually `main` or `master`.

workBranch

The branch on which the CI job was run

phabricatorDiff

A Phabricator Diff ID associated with the run, if any.

gitlabMergeRequestIID

A GitLab merge request IID associated with the run, if any.

repo

The repository URL

compareThreshold

The comparison threshold used for comparisons associated with this run.

url

The URL of this run

batch

The batch name associated with this run

report

The report object that was generated

Expand contents

id

The ID of this report

Ready to get started?

Sign up or contact us.