# HTTP Webhooks

Enabling HTTP Webhook Integration will trigger an HTTP POST request to an endpoint of your choice.

Currents will send a POST request for the following lifecycle event of Cypress or Playwright tests run:

* a new run starts
* a run finishes
* a run times out
* a run is cancelled

{% hint style="info" %}
Please note: The endpoint should be publicly accessible
{% endhint %}

### Examples

#### Example of HTTP POST request with cypress tests run data

```bash
curl --location --request POST 'https://yourserver.com/webhook/currents.dev' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event": "RUN_START",
    "runUrl": "https://app.currents.dev/run/950a13c3edf4f28b6e8ce301a404b4aa",
    "buildId": "demo-build-cdx3314",
    "commit": {
        "authorEmail": "john@doe.com",
        "authorName": "John Doe",
        "defaultBranch": "main",
        "branch": "feature-A",
        "message": "feat: change button color",
        "remoteOrigin": "https://github.com/org/repo.git",
        "sha": "5a7edc9a156e417068060d67109021351fc7d9b8"
    },
    "failures": 0,
    "flaky": 0,
    "overall": 1,
    "passes": 1,
    "pending": 0,
    "retries": 0,
    "skipped": 0
}'
```

#### HTTP Webhook Integration payload schema

```json
{
	event: "RUN_START" | "RUN_FINISH" | "RUN_TIMEOUT" | "RUN_CANCELED";
	runUrl: string;  // currents dashoard run URL
	buildId: string; // as reported by CI
	groupId: string; // only for multigroup runs
	tags: string[];
	commit: {
		sha: string | null;
		branch: string | null;
		authorName: string | null;
		authorEmail: string | null;
		message: string  | null;
		remoteOrigin: string | null;
		defaultBranch: string | null;
	},
	overall: number;  // overall number of tests
	passes: number;   // number of passed tests 
	failures: number; // number of failed tests 
	pending: number;  // number of pending tests
	skipped: number;  // number of skipped tests
	retries: number;  // number of test retries for the run
	flaky: number;    // number of flaky tests for the run
}
```

### Security

Validate the authenticity of Currents webhooks by setting custom HTTP headers.

#### Timestamp

Currents includes an `x-timestamp` HTTP header with the system's epoch timestamp for each webhook request to help you prevent replay attacks. Make sure your server's clock is synchronized with a reliable time source to avoid validation issues.

#### Custom Headers

You can set custom headers to pass a secret key with each webhook request.

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FTSjPT7OHZNr05JnBTvtc%2FScreenshot%202026-01-19%20at%2020.10.03.png?alt=media&#x26;token=c7f8c351-8ac0-4253-8339-54704cda55b7" alt=""><figcaption><p>Add a secret key in the headers so that your system can validate that the request came from Currents.</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.currents.dev/resources/integrations/http-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.