Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/21st-dev/1code/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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

Return a 200 response immediately after receiving the webhook. Perform heavy processing asynchronously.
Webhooks may be delivered more than once. Use the task_id to deduplicate events.
Always verify webhook signatures to prevent spoofed requests.
Webhook URLs must use HTTPS in production to ensure secure delivery.

Build docs developers (and LLMs) love

Get started for freeTalk to us