` |
| `Tuist-Event-Id` | The event `id` (for deduplication) |
| `Tuist-Event-Type` | The event `type` (for routing without parsing the body) |
| `User-Agent` | `Tuist-Webhooks/1.0` |
**Signature construction** (following Stripe’s scheme):
1. Concatenate the Unix timestamp, a `.` character, and the raw JSON request body: `{timestamp}.{payload}`
2. Compute HMAC-SHA256 using the endpoint’s signing secret as the key.
3. The consumer verifies by recomputing the HMAC and comparing in constant time. Reject events where the timestamp is more than 5 minutes old to prevent replay attacks.
### Delivery Behavior
| Property | Value |
| --- | --- |
| Retry strategy | Exponential backoff: 1m, 5m, 30m, 2h, 8h, 24h |
| Success condition | Any 2xx response within 10 seconds |
| Failure conditions | Non-2xx status, timeout, TLS error, DNS failure |
| Ordering | Not guaranteed. Consumers must not depend on event order. |
| Idempotency | Events include a stable `id`. Consumers should deduplicate on `Tuist-Event-Id`. |
| Delivery log | Dashboard shows last 30 days of deliveries per endpoint with status, latency, and manual redeliver button. |
### Full Example: `test_case.updated` Event (transition to muted)
A test case transitioning from `enabled` to `muted`. Consumers detect the transition by comparing `object.state` against `previous_attributes.state`.
```json
{
"id": "evt_1RqK4hJf2a9B7cXy",
"type": "test_case.updated",
"created": 1744206720,
"project": {
"id": "proj_abc123",
"full_name": "tuist/tuist"
},
"object": {
"id": "tc_xyz789",
"object": "test_case",
"name": "test_cache_warm_with_external_only",
"suite": "CacheWarmServiceTests",
"module": "TuistKitTests",
"state": "muted",
"labels": ["flaky"],
"url": "https://tuist.dev/tuist/tuist/test-cases/tc_xyz789"
},
"previous_attributes": {
"state": "enabled",
"labels": []
},
"request": {
"id": "auto_flaky_eval_20260411"
}
}
```
### Full Example: `test_case.updated` Event (recovery to enabled)
The same event type covers the recovery case. The transition direction is visible from `previous_attributes`.
```json
{
"id": "evt_2TsM5kLg3b0C8dZw",
"type": "test_case.updated",
"created": 1744212120,
"project": {
"id": "proj_abc123",
"full_name": "tuist/tuist"
},
"object": {
"id": "tc_xyz789",
"object": "test_case",
"name": "test_cache_warm_with_external_only",
"suite": "CacheWarmServiceTests",
"module": "TuistKitTests",
"state": "enabled",
"labels": [],
"url": "https://tuist.dev/tuist/tuist/test-cases/tc_xyz789"
},
"previous_attributes": {
"state": "muted",
"labels": ["flaky"]
},
"request": {
"id": "auto_recovery_eval_20260411"
}
}
```
### Future Example: `build.updated` Event
To illustrate extensibility, this uses the same envelope with a different `object` payload:
```json
{
"id": "evt_9XnP3qRs7d4E1fAv",
"type": "build.updated",
"created": 1744210000,
"project": {
"id": "proj_abc123",
"full_name": "tuist/tuist"
},
"object": {
"id": "build_def456",
"object": "build",
"state": "failed",
"duration_seconds": 342,
"cache_hit_rate": 78.5,
"target_count": 42,
"error_count": 3,
"url": "https://tuist.dev/tuist/tuist/builds/build_def456"
},
"previous_attributes": {
"state": "running",
"duration_seconds": null,
"error_count": 0
},
"request": {
"id": "req_cli_upload_xyz"
}
}
```
### JIRA Integration Example
A Cloudflare Worker that creates JIRA tickets for silenced tests:
```javascript
export default {
async fetch(request, env) {
// 1. Verify signature
const signature = request.headers.get("Tuist-Signature");
const body = await request.text();
if (!verifySignature(body, signature, env.TUIST_WEBHOOK_SECRET)) {
return new Response("Invalid signature", { status: 401 });
}
const event = JSON.parse(body);
// 2. Deduplicate
const seen = await env.KV.get(`evt:${event.id}`);
if (seen) return new Response("Already processed", { status: 200 });
// 3. Handle test silencing events. We listen to test_case.updated and
// detect a transition into a silenced state by comparing previous_attributes
// against the new object state. This naturally fires once per actual
// transition, regardless of how many subsequent updates touch the resource.
const prev = event.previous_attributes ?? {};
const becameSilenced =
event.type === "test_case.updated" &&
"state" in prev &&
prev.state === "enabled" &&
(event.object.state === "muted" || event.object.state === "skipped");
if (becameSilenced) {
const tc = event.object;
await fetch("https://your-org.atlassian.net/rest/api/3/issue", {
method: "POST",
headers: {
"Authorization": `Basic ${btoa(`user@org.com:${env.JIRA_API_TOKEN}`)}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
fields: {
project: { key: "MOBILE" },
issuetype: { name: "Bug" },
summary: `Flaky test silenced: ${tc.suite}/${tc.name}`,
description: {
type: "doc",
version: 1,
content: [{
type: "paragraph",
content: [{
type: "text",
text: [
`Test "${tc.name}" in ${tc.module} was ${tc.state}.`,
`Dashboard: ${tc.url}`,
].join(" "),
}],
}],
},
labels: ["flaky-test", "auto-created"],
},
}),
});
}
// 4. Mark as processed
await env.KV.put(`evt:${event.id}`, "1", { expirationTtl: 86400 * 30 });
return new Response("OK", { status: 200 });
},
};
function verifySignature(payload, header, secret) {
const parts = Object.fromEntries(
header.split(",").map((p) => p.split("=", 2))
);
const signed = `${parts.t}.${payload}`;
const encoder = new TextEncoder();
// Use Web Crypto API for HMAC-SHA256 verification
// (simplified. production code should use constant-time comparison)
return crypto.subtle.verify(
"HMAC",
crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]),
hexToBuffer(parts.v1),
encoder.encode(signed)
);
}
```
## Relationship to Automations Evolution
The [Automations Evolution RFC](https://community.tuist.dev/t/automations-evolution/964) proposes composable automation actions including `send_webhook`. The two systems are complementary:
- **This RFC** defines the webhook infrastructure: event envelope format, endpoint management, signing, delivery, and retries.
- **Automations** define the triggers: when conditions are met, an automation can fire a `send_webhook` action that delivers through this infrastructure.
The event format and delivery mechanics described here are designed to be reused by the automations system. An automation’s `send_webhook` action would produce an event with the same envelope, deliver it through the same retry pipeline, and show up in the same delivery log.
## Alternatives Considered
### 1. Direct JIRA / Linear integrations
Building first-party integrations provides a smoother setup experience but does not scale. Every new tool requires dedicated development and maintenance. A webhook is the universal building block that unlocks all integrations. We still should consider adding first-party integrations for the most common tools used by teams, but webhooks ensure that teams can ingest data and integrate with _any_ system before we might add support for it.
### 2. Polling the API
Teams could poll Tuist’s API for state changes. This is inefficient, introduces latency, and puts unnecessary load on the API. Push-based webhooks are the industry standard for event-driven integrations.
### 3. Entity-specific webhook designs
We could design a bespoke webhook payload for test silencing events, another for builds, another for cache, etc. This leads to inconsistent consumer code and more maintenance. The uniform Stripe-style envelope means one parser handles all entity types.
## Open Questions
1. **Batch events**. When an automation silences 50 tests at once, should we send 50 individual events or allow a batch envelope? Individual events are simpler and match Stripe’s model, but a batch mode could reduce noise for consumers that want to aggregate (e.g., one JIRA ticket for all tests silenced in a single action). I’d personally start with sending individual events and we can add batching down the line.
---
### Author:  [@pepicrft](https://community.tuist.dev/u/pepicrft)
#### Post date: [April 12, 2026, 1:33pm UTC](https://community.tuist.dev/t/rfc-webhooks-for-tuist-events/969/2 "2026-04-12T13:33:29Z")
Very onboard with this. Can’t think of a platform for developers that doesn’t add webhooks sooner or later. There are a couple of things that came to my mind while reading this.
### Storage
When building on GitHub webhooks, I found it useful to have a UI that shows the delivered webhooks (request headers, body, response…), with an option to resend them, for example, to confirm that a fix on their end works. Is this something you’d scope as part of this initial work? Or at least store them, and we can build this UI in a follow-up.
### Local development
When building an integration with webhooks, it’s very convenient to forward them to a locally running instance of your server, so I was thinking we could make this convenient for users through the CLI. Otherwise, they have to bring an additional tunnel, which adds unnecessary friction in the process of building on us.
### Grouping
How would you model this from the Elixir side? Were you thinking about creating an Oban worker per event, and then letting Oban run those? If so, I was thinking whether it’d make sense to do some batching, not for the use case you mention above, but to make efficient use of the HTTP connections. For example, if we receive 100 events going to the same URL in a short period of time, we could warm a Finch pool of connections and schedule some of them for the same pool. We can also treat this as a future optimization.
---
### Author:  [@marekfort](https://community.tuist.dev/u/marekfort)
#### Post date: [April 12, 2026, 1:42pm UTC](https://community.tuist.dev/t/rfc-webhooks-for-tuist-events/969/3 "2026-04-12T13:42:50Z")
> [@pepicrft](#):
>
> Or at least store them, and we can build this UI in a follow-up.
I agree we should store them, and the UI can be added in a follow-up.
> [@pepicrft](#):
>
> When building an integration with webhooks, it’s very convenient to forward them to a locally running instance of your server, so I was thinking we could make this convenient for users through the CLI. Otherwise, they have to bring an additional tunnel, which adds unnecessary friction in the process of building on us.
That’s a good idea 👍 We can and should do that.
> [@pepicrft](#):
>
> How would you model this from the Elixir side? Were you thinking about creating an Oban worker per event, and then letting Oban run those? If so, I was thinking whether it’d make sense to do some batching, not for the use case you mention above, but to make efficient use of the HTTP connections. For example, if we receive 100 events going to the same URL in a short period of time, we could warm a Finch pool of connections and schedule some of them for the same pool. We can also treat this as a future optimization.
Yes, I planned to use Oban workers. I think some batching might be useful, I’ll take that into account during the implementation and will see if, initially, we would just limit the worker concurrency and let those events wait in the Oban queue or if it would make sense to outright batch them.