Webhooks & Integrations

Connect Ovvoc to your existing tools with webhooks and integrations. Available on the Growth plan and above.

Slack notifications

The built-in Slack integration sends notifications directly to a channel of your choice. Configure it from Dashboard → Settings → Notifications.

🔄 ovvoc: Update completed
  Repository: acme/api-server
  Dependency: express 4.21.0 → 5.2.1
  Status: ✅ PR created (#42)
  Confidence: 0.95
  View PR: https://github.com/acme/api-server/pull/42

Custom webhooks

Send events to any HTTPS endpoint. Configure webhooks from your dashboard with the following options:

• Endpoint URL: Must be HTTPS
• Events: Select which events to receive
• Signing secret: HMAC-SHA256 signature for verification

Event types

Payload examples

{
  "event": "job.completed",
  "timestamp": "2026-02-10T14:30:00Z",
  "data": {
    "job_id": 1847,
    "repository": "acme/api-server",
    "dependency": "express",
    "from_version": "4.21.0",
    "to_version": "5.2.1",
    "category": "breaking_change",
    "confidence": 0.95,
    "duration_seconds": 42,
    "pr_url": "https://github.com/acme/api-server/pull/42"
  }
}

{
  "event": "job.failed",
  "timestamp": "2026-02-10T14:30:00Z",
  "data": {
    "job_id": 1848,
    "repository": "acme/api-server",
    "dependency": "jest",
    "from_version": "28.1.0",
    "to_version": "30.0.0",
    "failed_stage": "test",
    "error_summary": "3 tests failed after transform",
    "report_url": "https://app.ovvoc.com/jobs/1848"
  }
}

Verifying webhook signatures

Every webhook request includes an X-Ovvoc-Signature header containing an HMAC-SHA256 signature of the request body:

import crypto from 'node:crypto';

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf-8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express handler:
app.post('/webhooks/ovvoc', (req, res) => {
  const sig = req.headers['x-ovvoc-signature'];
  if (!verifyWebhook(req.body, sig, process.env.OVVOC_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  // Process event...
  res.status(200).send('OK');
});

Retry behavior

If your endpoint returns a non-2xx status code, Ovvoc retries with exponential backoff:

• 1st retry: after 10 seconds
• 2nd retry: after 60 seconds
• 3rd retry: after 5 minutes

After 3 failed attempts, the delivery is marked as failed. You can view failed deliveries and retry them manually from the dashboard.

CI/CD patterns

GitHub Actions trigger

Use the pr.created webhook to trigger additional CI/CD workflows:

name: ovvoc Update Notification
on:
  repository_dispatch:
    types: [ovvoc-pr-created]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Notify team
        uses: slackapi/[email protected]
        with:
          channel-id: 'C0123456'
          slack-message: |
            New ovvoc PR: ${{ github.event.client_payload.pr_url }}
            Dependency: ${{ github.event.client_payload.dependency }}
            Confidence: ${{ github.event.client_payload.confidence }}

Deploy triggers

Listen for pr.merged events to trigger deployments automatically when Ovvoc PRs are merged by your team.

Webhook event types in detail

Each webhook event carries a structured JSON payload with all the information you need to act on it programmatically. Here is a comprehensive breakdown of every event type:

• update.detected — fired when Ovvoc detects a new version available for a dependency in one of your repositories. The payload includes the repository name, package name, current version, available version, category classification, and severity level.
• job.started — fired when a pipeline execution begins for an update. The payload includes the job ID, repository, dependency, target version, and the selected strategy (version-only, AST transform, or AI-assisted).
• job.completed — fired when a pipeline finishes successfully and a PR has been created. The payload includes the job ID, repository, dependency, version range, confidence score, total duration, and the PR URL.
• job.failed — fired when a pipeline fails at any stage. The payload includes the job ID, repository, dependency, the failed stage name, a summary of the error, and a link to the full failure report in the dashboard.
• pr.created — fired when Ovvoc opens a pull request on your repository. The payload includes the PR number, PR URL, dependency, version range, confidence score, and the number of files changed.
• pr.merged — fired when an Ovvoc-created pull request is merged (by your team or by auto-merge rules). The payload includes the PR number, merge timestamp, and the dependency that was updated.
• security.advisory — fired when a security vulnerability is detected in one of your dependencies. The payload includes the advisory ID, severity (critical, high, moderate, low), affected package and version range, and the recommended fix version.

Every event payload includes the event type string, a timestamp in ISO 8601 format, and a data object containing the event-specific fields listed above.

Slack integration setup

The built-in Slack integration is the fastest way to get notified about Ovvoc activity. Here is how to set it up step by step:

1. Go to your Slack workspace’s App Directory and create an Incoming Webhook. Select the channel where you want notifications to appear.
2. Copy the webhook URL that Slack provides (it looks like https://hooks.slack.com/services/T.../B.../...).
3. In your Ovvoc dashboard, go to Settings → Notifications and paste the Slack webhook URL.
4. Select which event types you want to receive in Slack. We recommend starting with pr.created, job.failed, and security.advisory.
5. Click Test to send a sample notification to your channel and verify the integration is working.

Events are formatted as rich Slack messages with color-coded attachments. A successful PR notification looks like: “Ovvoc opened PR #42: Update lodash to 4.17.21 (confidence: 100%)” with a green sidebar. Failed jobs show a red sidebar with the failure stage and error summary.

CI/CD integration patterns

Webhooks enable powerful automation patterns when combined with your existing CI/CD infrastructure. Here are the most common patterns:

Triggering downstream pipelines

Use the job.completed webhook to notify your CI system that an Ovvoc PR is ready for additional testing. Your CI can run integration tests, security scans, or performance benchmarks on the PR branch before your team reviews it.

Auto-merge workflow

For high-confidence updates (confidence 1.0, categories 1–6), you can set up an auto-merge pattern: Ovvoc creates the PR, your webhook triggers CI, CI runs the full test suite, and if all checks pass, the PR is automatically merged. This is ideal for version-only updates and security patches where no code changes are involved.

Staging deployment

Use the pr.created event to automatically deploy the PR branch to a staging environment. This lets your QA team verify the update in a realistic environment before merging. The pr.merged event can then trigger the production deployment.

Custom webhook handler

Building a custom webhook handler is straightforward. Your endpoint should accept POST requests with a JSON body, verify the signature, process the event, and return a 200 status code. Here is the general pattern:

1. Receive the POST request at your configured HTTPS endpoint
2. Verify the X-Ovvoc-Signature header using your signing secret (see the signature verification example above)
3. Parse the JSON body and check the event field to determine the event type
4. Process the event based on its type — for example, send a notification, update a tracking system, or trigger a deployment
5. Respond with 200 OK as quickly as possible. Perform any slow processing asynchronously after responding.

The payload always includes the event type, timestamp, and a data object with event-specific fields including job_id, repository information, and update details. Unrecognized event types should be ignored gracefully to ensure forward compatibility as new events are added.

Delivery guarantees

Ovvoc provides at-least-once delivery for all webhook events. Here are the specifics:

• Retries: If your endpoint returns a non-2xx status code or times out, Ovvoc retries the delivery 3 times with exponential backoff: 1st retry after 10 seconds, 2nd retry after 60 seconds, 3rd retry after 5 minutes.
• Timeout: Each delivery attempt has a 10-second timeout. If your endpoint does not respond within 10 seconds, the attempt is considered failed and will be retried.
• Failed deliveries: After 3 failed attempts, the delivery is marked as failed in the dashboard. You can view all failed deliveries under Settings → Webhooks → Delivery Log and retry them manually.
• Idempotency: Because Ovvoc provides at-least-once delivery (not exactly-once), your webhook handler may receive the same event more than once in rare cases (e.g., network issues during the 200 OK response). Design your handlers to be idempotent — use the job_id or event timestamp to deduplicate events if needed.
• Ordering: Events are delivered in approximate chronological order, but strict ordering is not guaranteed. A job.completed event may arrive before or after the corresponding pr.created event.