Webhooks Overview

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 a GitHub integration to Notra, webhooks are automatically configured to send event notifications to your organization's webhook endpoint:

POST https://api.usenotra.com/api/webhooks/{provider}/{organizationId}/{integrationId}/{repositoryId}

Supported Providers

Notra currently supports webhooks from GitHub. Other integrations (such as Linear) connect via direct API access and do not use webhooks.

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);}

X-Hub-Signature-256: sha256=7d38cdd689735b008b3c702edd92eea23791c5f6

Setting Up Webhooks

Webhooks are automatically configured when you:

1. Connect an Integration - Navigate to your organization settings and connect GitHub
2. Add a Repository - Add specific repositories you want to track
3. Enable Event Triggers - Configure which events should trigger workflows

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 hoursasync function isDeliveryProcessed(deliveryId: string) {  const key = `webhook:delivery:${deliveryId}`;  const exists = await redis.exists(key);  return exists === 1;}

{  "received": true,  "message": "Webhook already processed (duplicate delivery)",  "data": {    "event": "push",    "delivery": "12345678-1234-1234-1234-123456789abc",    "duplicate": true  }}

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"}

{  "error": "Integration is disabled"}

{  "error": "Missing X-GitHub-Event header"}

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:

{  "received": true,  "message": "Pong! Webhook configured successfully",  "data": {    "event": "ping",    "delivery": "12345678-1234-1234-1234-123456789abc"  }}

Next Steps