Webhooks

Get real-time notifications when tasks complete

Overview

Webhooks allow you to receive real-time notifications when agent tasks complete. Instead of polling the API, 1Code will send an HTTP POST request to your specified webhook URL.

Setup

Provide a webhook_url when creating a task:

curl -X POST https://1code.dev/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "https://github.com/your-org/your-repo",
    "prompt": "Fix the failing tests",
    "webhook_url": "https://your-app.com/webhooks/1code"
  }'

Webhook Events

1Code sends webhook notifications for the following events:

• task.completed - Task finished successfully
• task.failed - Task failed with an error
• task.pr_created - Pull request created
• task.pr_merged - Pull request merged (if auto-merge enabled)

Webhook Payload

When an event occurs, 1Code sends a POST request to your webhook URL:

{
  "event": "task.completed",
  "task_id": "task_abc123",
  "status": "completed",
  "repository": "https://github.com/your-org/your-repo",
  "pr_url": "https://github.com/your-org/your-repo/pull/42",
  "pr_number": 42,
  "branch": "1code/fix-failing-tests",
  "commits": [
    {
      "sha": "abc123def",
      "message": "Fix: correct test assertions",
      "timestamp": "2026-03-04T10:30:00Z"
    }
  ],
  "completed_at": "2026-03-04T10:30:00Z",
  "created_at": "2026-03-04T10:00:00Z"
}

Payload Fields

event · string

Event type: task.completed, task.failed, task.pr_created, task.pr_merged

task_id · string

Unique task identifier

status · string

Final task status: completed, failed

repository · string

Repository URL

pr_url · string

Pull request URL (if created)

pr_number · number

Pull request number (if created)

branch · string

Branch name created by the agent

commits · array

Array of commit objects

error · string

Error message (if task failed)

completed_at · string

ISO 8601 timestamp when task completed

created_at · string

ISO 8601 timestamp when task was created

Webhook Endpoint Implementation

Node.js/Express

app.post('/webhooks/1code', (req, res) => {
  const { event, task_id, status, pr_url } = req.body;

  console.log(`Task ${task_id} ${event}`);

  if (event === 'task.completed') {
    console.log(`Pull request: ${pr_url}`);
    // Handle successful completion
  } else if (event === 'task.failed') {
    console.error(`Task failed: ${req.body.error}`);
    // Handle failure
  }

  // Respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

Security

Webhook Signatures

1Code signs webhook requests with a signature in the X-1Code-Signature header. Verify this signature to ensure the webhook is from 1Code:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/1code', (req, res) => {
  const signature = req.headers['x-1code-signature'];
  const webhookSecret = process.env.ONECODE_WEBHOOK_SECRET;

  if (!verifyWebhook(req.body, signature, webhookSecret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
  res.status(200).json({ received: true });
});

Webhook Secret

Your webhook secret is available in Settings > API Keys > Webhook Secret. Use it to verify webhook signatures.

Retry Policy

If your webhook endpoint returns a non-2xx status code, 1Code will retry the webhook:

• Retry schedule: 1min, 5min, 30min, 2h, 12h
• Max retries: 5 attempts
• Timeout: 10 seconds per request

Testing Webhooks

Local Testing

Use a tool like ngrok to expose your local server:

ngrok http 3000

Then use the ngrok URL as your webhook URL:

https://abc123.ngrok.io/webhooks/1code

Webhook Logs

View webhook delivery logs in your dashboard at Settings > Webhooks to debug failed deliveries.

Best Practices

Respond quickly

Return a 200 response immediately after receiving the webhook. Perform heavy processing asynchronously.

Handle duplicates

Webhooks may be delivered more than once. Use the task_id to deduplicate events.

Verify signatures

Always verify webhook signatures to prevent spoofed requests.

Use HTTPS

Webhook URLs must use HTTPS in production to ensure secure delivery.