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.

string

required

push

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

interface PushEvent {
  type: 'push';
  action: 'pushed';
  data: {
    ref: string;
    branch: string;
    commits: Array<{
      id: string;
      message: string;
      author: {
        name: string;
        email: string;
        username?: string;
      };
      timestamp: string;
      url: string;
    }>;
    headCommit: {
      id: string;
      message: string;
    } | null;
  };
}

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.

string

required

release

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

interface ReleaseEvent {
  type: 'release';
  action: 'published' | 'prereleased';
  data: {
    tagName: string;
    name: string | null;
    body: string | null;
    prerelease: boolean;
    draft: boolean;
    publishedAt: string | null;
    url: string;
  };
}

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.

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.

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

{
  "source": "github_webhook",
  "eventType": "push",
  "repository": "owner/repo"
}

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": []
  }
}

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

Event Logging

All webhook events are logged for debugging and monitoring:

Log Structure

string

required

Unique log identifier (e.g., log_a1b2c3d4)

string

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

string

required

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

string

required

Integration type such as github or linear.

string

required

incoming or outgoing

string

required

success, failed, or pending

number

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

string

Error description if status is failed

object

Event data and metadata

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

{
  "id": "log_x9y8z7w6",
  "referenceId": "87654321-4321-4321-4321-cba987654321",
  "title": "Invalid webhook signature",
  "integrationType": "github",
  "direction": "incoming",
  "status": "failed",
  "statusCode": 401,
  "errorMessage": "Invalid webhook signature",
  "payload": null,
  "createdAt": "2024-03-02T10:35:00.000Z"
}

{
  "id": "log_m5n6o7p8",
  "referenceId": "11112222-3333-4444-5555-666677778888",
  "title": "Filtered push event",
  "integrationType": "github",
  "direction": "incoming",
  "status": "success",
  "statusCode": 200,
  "errorMessage": null,
  "payload": {
    "event": "push",
    "action": "pushed",
    "filtered": true
  },
  "createdAt": "2024-03-02T10:40: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

Guides

Webhooks

Endpoints

GitHub Events

Push Event

Payload Structure

Event Filtering

Headers

Release Event

Payload Structure

Event Filtering

Headers

Ping Event

Payload Structure

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

​GitHub Events

​Push Event

​Payload Structure

​Event Filtering

​Headers

​Release Event

​Payload Structure

​Event Filtering

​Headers

​Ping Event

​Payload Structure

​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

GitHub Events

Push Event

Payload Structure

Event Filtering

Headers

Release Event

Payload Structure

Event Filtering

Headers

Ping Event

Payload Structure

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