Skip to main content

​
Webhooks

Webhooks allow Notra to receive real-time notifications when events occur in your connected integrations. Instead of polling for changes, webhooks push data to Notra immediately when events happen.

​
How Webhooks Work

When you connect an integration (like GitHub or Linear) to Notra, webhooks are automatically configured to send event notifications to your organization’s webhook endpoint: 
POST https://api.notra.ai/api/webhooks/{provider}/{organizationId}/{integrationId}/{repositoryId}

​
Supported Providers

Notra currently supports webhooks from the following providers:

GitHub

Receive notifications for pushes, releases, and more

Linear

Track issue updates and project changes

​
Webhook Security

All webhook requests are secured using cryptographic signatures to ensure they originate from legitimate sources.

​
GitHub Signature Verification

GitHub webhooks use HMAC SHA-256 signatures sent in the X-Hub-Signature-256 header. Notra automatically verifies these signatures before processing any webhook payload. 
import crypto from 'node:crypto';

function verifySignature(payload: string, signature: string, secret: string) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = `sha256=${hmac.update(payload).digest('hex')}`;
  const digestBuffer = Buffer.from(digest);
  const signatureBuffer = Buffer.from(signature);
  
  if (digestBuffer.length !== signatureBuffer.length) {
    return false;
  }
  
  return crypto.timingSafeEqual(digestBuffer, signatureBuffer);
}
Webhook secrets are automatically generated and managed by Notra when you connect an integration. You don’t need to manually configure them.

​
Linear Signature Verification

Linear webhooks include a Linear-Signature header for authentication. Notra validates this signature before processing Linear events. 
Linear-Signature: <signature-value>

​
Setting Up Webhooks

Webhooks are automatically configured when you:
  1. Connect an Integration - Navigate to your organization settings and connect GitHub or Linear
  2. Add a Repository - For GitHub integrations, add specific repositories you want to track
  3. Enable Event Triggers - Configure which events should trigger workflows
Make sure your integration is enabled. Webhooks from disabled integrations will be rejected with a 403 status code.

​
Webhook Delivery

​
Duplicate Prevention

Notra automatically prevents duplicate webhook processing using the delivery ID:
  • GitHub: Uses the X-GitHub-Delivery header to track deliveries
  • Deliveries are cached for 24 hours to prevent reprocessing
  • Duplicate deliveries return a success response without reprocessing
const DELIVERY_TTL_SECONDS = 60 * 60 * 24; // 24 hours

async function isDeliveryProcessed(deliveryId: string) {
  const key = `webhook:delivery:${deliveryId}`;
  const exists = await redis.exists(key);
  return exists === 1;
}

​
Webhook Responses

​
Success Response

When a webhook is successfully processed: 
{
  "received": true,
  "message": "Processed push event (pushed)",
  "data": {
    "event": "push",
    "delivery": "12345678-1234-1234-1234-123456789abc",
    "processed": {
      "type": "push",
      "action": "pushed",
      "data": { ... }
    },
    "repository": {
      "id": 123456,
      "fullName": "owner/repo"
    }
  }
}

​
Error Responses

​
400 Bad Request
error
Invalid webhook parameters, missing headers, or malformed payload
​
401 Unauthorized
error
Invalid webhook signature - the request could not be authenticated
​
403 Forbidden
error
Integration disabled, or repository doesn’t belong to the integration
​
404 Not Found
error
Integration or repository not found
​
500 Internal Server Error
error
Server error while processing the webhook
{
  "error": "Invalid webhook signature"
}

​
Webhook Logging

Notra automatically logs all webhook deliveries for debugging and monitoring:
  • Retention Period: 7 or 30 days depending on your plan
  • Log Details: Status, payload, timestamps, error messages
  • Access: View logs in your organization dashboard under Integrations
await appendWebhookLog({
  organizationId,
  integrationId,
  integrationType: 'github',
  title: 'Processed push event',
  status: 'success',
  statusCode: 200,
  referenceId: delivery,
  payload: { event, action, data },
  retentionDays: 30
});

​
Testing Webhooks

​
Ping Event

GitHub automatically sends a ping event when a webhook is first configured. Notra responds to ping events to confirm the webhook is set up correctly:
Ping Response
{
  "received": true,
  "message": "Pong! Webhook configured successfully",
  "data": {
    "event": "ping",
    "delivery": "12345678-1234-1234-1234-123456789abc"
  }
}
You can manually trigger a ping event from your GitHub repository settings under Webhooks to test connectivity.

​
Next Steps

Event Types

Learn about specific event types and their payloads

Triggers

Configure automated workflows based on webhook events

Build docs developers (and LLMs) love

Get started for freeTalk to us