Webhooks

Supported Events

Subscribe to one or more of the following events when configuring a webhook.

Creating a Webhook

Via Dashboard

1. Navigate to your project in the Euriqa dashboard at app.euriqa.dev.
2. Go to Settings > Webhooks.
3. Click Add Webhook.
4. Enter the webhook URL, select the events to subscribe to, and optionally add custom headers or a secret.
5. Click Save. The webhook is now active.

Via API

curl -X POST https://app.euriqa.dev/api/webhooks \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["run.completed", "run.failed"],
    "headers": {
      "Authorization": "Bearer your-token"
    },
    "secret": "whsec_your_webhook_secret",
    "active": true
  }'

URL Requirements

Webhook endpoint URLs must meet the following requirements:

• Must use HTTPS (HTTP is not allowed for security reasons).
• Must be a publicly accessible URL. Internal or private network addresses are not supported.
• Must respond with a 2xx status code within 10 seconds.
• Must accept POST requests with a JSON body.

Managing Webhooks

Use the API to list, update, and delete webhooks programmatically.

List Webhooks

curl https://app.euriqa.dev/api/webhooks \
  -H "X-API-Key: your-api-key"

Update a Webhook

curl -X PATCH https://app.euriqa.dev/api/webhooks/whk_abc123 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/new-webhook-endpoint",
    "events": ["run.failed"],
    "active": true
  }'

Delete a Webhook

curl -X DELETE https://app.euriqa.dev/api/webhooks/whk_abc123 \
  -H "X-API-Key: your-api-key"

Custom Headers

Add custom HTTP headers to every webhook delivery. This is useful for authentication tokens, routing keys, or any metadata your endpoint requires.

{
  "headers": {
    "Authorization": "Bearer your-service-token",
    "X-Routing-Key": "test-results",
    "X-Environment": "production"
  }
}

Custom headers are sent alongside the standard Euriqa headers on every delivery. They are stored securely and can be updated at any time via the dashboard or API.

Webhook Secret

Each webhook can have an optional secret used to sign request payloads. When a secret is configured, every delivery includes an X-Euriqa-Signature header containing an HMAC-SHA256 signature of the request body.

Your endpoint should verify this signature to confirm the request genuinely came from Euriqa. This prevents attackers from spoofing webhook deliveries.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Example: Slack Integration

Send test run results to a Slack channel using an incoming webhook URL. Subscribe to run.completed to get notified on every run, or run.failed to only hear about failures.

{
  "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  "events": ["run.completed"],
  "headers": {},
  "secret": "whsec_slack_integration_secret",
  "active": true
}

Euriqa formats the payload as a JSON POST request. You can use a middleware service or Slack workflow to transform the payload into a Slack message block format, or use a tool like Zapier or n8n to bridge the two.

Example: Deployment Gate

Use webhooks to gate deployments on test results. When a test run completes, your webhook endpoint can check the results and approve or block the deployment accordingly.

{
  "url": "https://your-deploy-service.com/api/gate",
  "events": ["run.completed"],
  "headers": {
    "Authorization": "Bearer deploy-service-token",
    "X-Pipeline-Stage": "pre-deploy"
  },
  "secret": "whsec_deploy_gate_secret",
  "active": true
}

The webhook payload includes the full run summary with pass/fail counts, duration, branch, and commit SHA. Your deployment gate service can use this data to make an informed decision:

• All tests passed -- Approve the deployment and trigger the next pipeline stage.
• Tests failed -- Block the deployment and notify the team via Slack or email.
• Flaky tests detected -- Approve with a warning, or require manual review depending on your policy.