Webhook Events

Notra processes specific events from connected integrations and transforms them into actionable data for your workflows.

GitHub Events

Notra listens to the following GitHub webhook events:

Push Event

Triggered when commits are pushed to the default branch of a repository.

Event Type

string

required

push

Action

string

required

pushed

Payload Structure

{
  "type": "push",
  "action": "pushed",
  "data": {
    "ref": "refs/heads/main",
    "branch": "main",
    "commits": [
      {
        "id": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
        "message": "Add new feature",
        "author": {
          "name": "Jane Developer",
          "email": "jane@example.com",
          "username": "janedev"
        },
        "timestamp": "2024-03-02T10:30:00Z",
        "url": "https://github.com/owner/repo/commit/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"
      }
    ],
    "headCommit": {
      "id": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
      "message": "Add new feature"
    }
  }
}

Event Filtering

Push events are only processed when:

Commits are pushed to the default branch (usually main or master)

At least one commit is included in the push

Pushes to feature branches or tags are ignored. Only the default branch is tracked to reduce noise.

Headers

X-GitHub-Event: push
X-Hub-Signature-256: sha256=...
X-GitHub-Delivery: 12345678-1234-1234-1234-123456789abc
Content-Type: application/json

Release Event

Triggered when a new release is published or pre-released in a repository.

Event Type

string

required

release

Actions

string[]

required

published, prereleased

Payload Structure

{
  "type": "release",
  "action": "published",
  "data": {
    "tagName": "v1.2.0",
    "name": "Version 1.2.0",
    "body": "## What's Changed\n- New feature X\n- Bug fix Y",
    "prerelease": false,
    "draft": false,
    "publishedAt": "2024-03-02T14:30:00Z",
    "url": "https://github.com/owner/repo/releases/tag/v1.2.0"
  }
}

Event Filtering

Release events are only processed for:

Action is published or prereleased

Draft releases are excluded (unless action is created)

Draft releases are typically not processed to avoid triggering workflows on unpublished releases.

Headers

X-GitHub-Event: release
X-Hub-Signature-256: sha256=...
X-GitHub-Delivery: 12345678-1234-1234-1234-123456789abc
Content-Type: application/json

Ping Event

Sent by GitHub when a webhook is first configured or manually tested.

Event Type

string

required

ping

Payload Structure

{
  "event": "ping",
  "delivery": "12345678-1234-1234-1234-123456789abc"
}

Ping events are automatically acknowledged and do not trigger any workflows. They’re used solely for connectivity testing.

Linear Events

Linear webhook support is currently in development. Events are received and logged but not yet fully processed.

Supported Actions

Linear webhooks are acknowledged but event processing is not yet implemented. Check back for updates on Linear event support.

Headers

Linear-Signature: <signature>
Content-Type: application/json

Event Processing Pipeline

When a webhook event is received, Notra follows this processing pipeline:

Memory Storage

Processed events are stored in Notra’s memory system for AI context:

const dataSnippet = JSON.stringify({ 
  eventType, 
  repository, 
  action, 
  data 
});

const text = `GitHub ${eventType} event for ${repository} (${action}).\n\nData:\n${dataSnippet}`;

await fetch('https://api.supermemory.ai/v3/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: text.trim(),
    containerTag: organizationId,
    customId: `github:${repositoryId}:${deliveryId}`,
    metadata: {
      source: 'github_webhook',
      eventType,
      repository
    }
  })
});

Only push and release events are stored in memory. This provides your AI agents with context about recent code changes and releases.

Workflow Triggers

Webhook events can automatically trigger content workflows based on configured triggers:

Trigger Matching

// Find triggers matching this webhook event
const matchingTriggers = await db
  .select()
  .from(contentTriggers)
  .where(
    and(
      eq(contentTriggers.organizationId, organizationId),
      eq(contentTriggers.sourceType, 'github_webhook'),
      eq(contentTriggers.enabled, true),
      // Repository ID is in the targets array
      sql`(targets->'repositoryIds') @> ${JSON.stringify([repositoryId])}::jsonb`
    )
  );

// Trigger matching workflows
for (const trigger of matchingTriggers) {
  const eventTypes = trigger.sourceConfig.eventTypes ?? [];
  
  if (eventTypes.length === 0 || eventTypes.includes(eventType)) {
    await triggerEventNow({
      triggerId: trigger.id,
      eventType,
      eventAction,
      eventData,
      repositoryId,
      deliveryId
    });
  }
}

Event Type Filtering

Triggers can be configured to respond to specific event types:

{
  "sourceType": "github_webhook",
  "sourceConfig": {
    "eventTypes": []
  }
}

Event Logging

All webhook events are logged for debugging and monitoring:

Log Structure

string

required

Unique log identifier (e.g., log_a1b2c3d4)

referenceId

string

External delivery ID (e.g., GitHub’s X-GitHub-Delivery header)

title

string

required

Human-readable log title (e.g., “Processed push event”)

integrationType

string

required

Integration type: github, linear, slack, etc.

direction

string

required

incoming or outgoing

status

string

required

success, failed, or pending

statusCode

number

HTTP status code (200, 400, 401, etc.)

errorMessage

string

Error description if status is failed

payload

object

Event data and metadata

createdAt

string

required

ISO 8601 timestamp

Example Logs

{
  "id": "log_a1b2c3d4",
  "referenceId": "12345678-1234-1234-1234-123456789abc",
  "title": "Processed push event",
  "integrationType": "github",
  "direction": "incoming",
  "status": "success",
  "statusCode": 200,
  "errorMessage": null,
  "payload": {
    "event": "push",
    "action": "pushed",
    "data": { ... }
  },
  "createdAt": "2024-03-02T10:30:00.000Z"
}

Common Event Scenarios

Scenario 1: New Release Published

// GitHub sends release webhook
{
  "action": "published",
  "release": {
    "tag_name": "v2.0.0",
    "name": "Major Release 2.0",
    "body": "Breaking changes and new features",
    "prerelease": false
  },
  "repository": {
    "full_name": "acme/api"
  }
}

// Notra processes and stores in memory
// Triggers configured workflows
// Returns success response

Scenario 2: Push to Main Branch

// GitHub sends push webhook
{
  "ref": "refs/heads/main",
  "commits": [
    {
      "id": "abc123",
      "message": "Fix critical bug",
      "author": { "name": "Dev" }
    }
  ],
  "repository": {
    "default_branch": "main",
    "full_name": "acme/web"
  }
}

// Notra validates signature
// Processes push event
// Stores commit info in memory
// Triggers documentation update workflow

Scenario 3: Invalid Signature

// GitHub sends webhook with invalid signature
// X-Hub-Signature-256: sha256=invalid_signature

// Notra verifies signature fails
// Returns 401 error
// Logs failed attempt
{
  "error": "Invalid webhook signature"
}

Getting Started

Endpoints

Webhooks

Webhook Events

Webhook Events

GitHub Events

Push Event

Payload Structure

Event Filtering

Headers

Release Event

Payload Structure

Event Filtering

Headers

Ping Event

Payload Structure

Linear Events

Supported Actions

Headers

Event Processing Pipeline

Memory Storage

Workflow Triggers

Trigger Matching

Event Type Filtering

Event Logging

Log Structure

Example Logs

Common Event Scenarios

Scenario 1: New Release Published

Scenario 2: Push to Main Branch

Scenario 3: Invalid Signature

Next Steps

Webhooks Overview

Configure Triggers

Build docs developers (and LLMs) love

Getting Started

Endpoints

Webhooks

​Webhook Events

​GitHub Events

​Push Event

​Payload Structure

​Event Filtering

​Headers

​Release Event

​Payload Structure

​Event Filtering

​Headers

​Ping Event

​Payload Structure

​Linear Events

​Supported Actions

​Headers

​Event Processing Pipeline

​Memory Storage

​Workflow Triggers

​Trigger Matching

​Event Type Filtering

​Event Logging

​Log Structure

​Example Logs

​Common Event Scenarios

​Scenario 1: New Release Published

​Scenario 2: Push to Main Branch

​Scenario 3: Invalid Signature

​Next Steps

Webhooks Overview

Configure Triggers

Build docs developers (and LLMs) love

Webhook Events

GitHub Events

Push Event

Payload Structure

Event Filtering

Headers

Release Event

Payload Structure

Event Filtering

Headers

Ping Event

Payload Structure

Linear Events

Supported Actions

Headers

Event Processing Pipeline

Memory Storage

Workflow Triggers

Trigger Matching

Event Type Filtering

Event Logging

Log Structure

Example Logs

Common Event Scenarios

Scenario 1: New Release Published

Scenario 2: Push to Main Branch

Scenario 3: Invalid Signature

Next Steps