Skip to main content
You can configure webhooks to trigger on the following events. The event names shown here match what you’ll see in the Speckle UI, which uses the current Speckle terminology (project, model, version).
Event Name Mapping: While the UI displays events using current Speckle semantics (project, model, version), the actual webhook payloads use legacy event names from Speckle v1/v2 (stream, branch, commit) for backward compatibility. The payload examples below show the actual event_name values you’ll receive.Payload Content: Payloads contain reference data only (IDs, metadata), not full objects. Use the IDs with the GraphQL API or REST API to retrieve complete data.

​
Available Events

​
Project Events

  • project_update
  • project_delete
Payload Event Name: stream_updatePayload event.data:
{
  "streamId": "project-id",
  "changes": {
    "name": "Updated Project Name",
    "description": "Updated description"
  }
}

​
Model Events

  • model_create
  • model_update
  • model_delete
Payload Event Name: branch_createPayload event.data:
{
  "branchId": "branch-id",
  "branchName": "feature/new-feature",
  "description": "New feature branch"
}

​
Version Events

  • version_create
  • version_update
  • version_receive
  • version_delete
Payload Event Name: commit_createPayload event.data:
{
  "commitId": "commit-id",
  "branchName": "main",
  "message": "Initial commit",
  "authorName": "John Doe",
  "authorId": "user-id"
}

​
Comment Events

  • comment_created
  • comment_archived
  • comment_replied
Payload Event Name: comment_createdPayload event.data:
{
  "commentId": "comment-id",
  "text": "This looks great!",
  "resourceType": "commit",
  "resourceId": "commit-id",
  "authorId": "user-id"
}

​
Permission Events

  • project_permissions_add
  • project_permissions_remove
Payload Event Name: stream_permissions_addPayload event.data:
{
  "streamId": "project-id",
  "userId": "user-id",
  "role": "editor"
}

​
Issue Events

  • issue_created
  • issue_updated
  • issue_reply_created
  • issue_deleted
Payload Event Name: issue_createdPayload event.data:
{
  "issue": {
    "id": "issue-id",
    "title": "Bug in model",
    "description": "Found a bug...",
    "status": "open",
    "priority": "high"
  },
  "userId": "user-id"
}
The payload examples above show only the event.data field content. The full payload includes the base structure (stream, user, server, webhook info) as shown in the Payload Structure section above. Use the event.event_name field to determine which event occurred and parse the event.data accordingly. To retrieve the full object data, use the IDs provided in event.data with the GraphQL API or REST API endpoints.

​
Payload Structure

All webhook payloads follow this base structure: 
{
  "streamId": "project-id",
  "stream": {
    "id": "project-id",
    "name": "My Project",
    "description": "Project description",
    "isPublic": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "userId": "user-id",
  "user": {
    "id": "user-id",
    "name": "John Doe",
    "bio": "User bio",
    "company": "Company Name",
    "avatar": "https://...",
    "verified": true
  },
  "activityMessage": "Event description",
  "event": {
    "event_name": "event_type",
    "data": {
      // Event-specific data (see examples below)
    }
  },
  "server": {
    "name": "Speckle Server",
    "company": "Speckle Systems",
    "canonicalUrl": "https://app.speckle.systems"
  },
  "webhook": {
    "id": "webhook-id",
    "streamId": "project-id",
    "url": "https://your-endpoint.com/webhook",
    "description": "My Webhook",
    "enabled": true,
    "triggers": ["event_type"]
  }
}

​
Frequently Asked Questions

Choose events based on what actions you want to react to. For example:
  • Use version_create to trigger CI/CD builds when new versions are published
  • Use comment_created to send notifications when comments are added
  • Use issue_created to integrate with issue tracking systems
  • Use project_permissions_add to sync access control changes
You can subscribe to multiple events with a single webhook.
  • version_create: Triggered when a version is created/published from a connector or API (when data is uploaded/pushed)
  • version_receive: Triggered when a version is received/consumed by another service or application (e.g., when a connector receives data from another project, or when data is imported into a different application)
Use version_create for most CI/CD and automation workflows, as it fires when users actively publish data. Use version_receive to track when versions are consumed by downstream services or applications.
Yes! When creating a webhook, you can select multiple events. The same webhook endpoint will receive payloads for all selected events. Use the event.event_name field to determine which event occurred.
The UI uses current Speckle terminology (project, model, version), while payloads use legacy names (stream, branch, commit) from Speckle v1/v2 for backward compatibility. This ensures existing integrations continue to work. Always check the event.event_name field in the payload to see the actual event type.
Webhook payloads contain reference data (IDs, names, metadata) rather than full objects. This keeps payloads lightweight and secure. Use the IDs provided in the payload to fetch complete object data via the GraphQL API or REST API when needed.