Skip to main content

​
Overview

Webhooks allow you to receive real-time notifications when events occur in your Speckle projects. Instead of polling the API, you can configure webhooks to automatically send HTTP POST requests to your endpoint whenever specific events happen, such as when a new version is created or a comment is added. Webhooks are available on any Speckle server, including app.speckle.systems and self-hosted instances.
Webhooks vs Subscriptions: Webhooks are HTTP-based and ideal for server-to-server integrations. For client applications (web apps, desktop apps) that need real-time UI updates, consider using GraphQL Subscriptions instead, which use WebSocket connections.

​
Use Cases

Webhooks are ideal for:
  • CI/CD Pipelines: Trigger automated builds or tests when new versions are created
  • Orchestration: Coordinate complex multi-step workflows across different systems and services
  • Automation Workflows: Integrate Speckle events into your existing automation systems
  • Notifications: Send alerts to external systems when important events occur
  • Data Synchronization: Keep external databases or systems in sync with Speckle data
  • Custom Integrations: Build custom applications that react to Speckle events

​
Orchestration

Webhooks enable powerful orchestration scenarios where Speckle events trigger coordinated workflows across multiple systems:
  • Multi-System Workflows: Chain together actions across different platforms (e.g., when a version is created, trigger a build in CI, update a project management tool, and notify stakeholders)
  • Event-Driven Architecture: Build event-driven systems where Speckle events initiate complex business processes
  • Workflow Coordination: Coordinate dependent tasks across different services, ensuring proper sequencing and error handling
  • Cross-Platform Integration: Connect Speckle with other tools in your tech stack (design tools, analysis software, project management, etc.) to create seamless workflows
  • Conditional Logic: Implement conditional workflows that branch based on event data (e.g., different actions for different project types or user roles)
  • State Management: Track workflow state across distributed systems, using webhooks to update state machines or orchestration engines
Orchestration with webhooks allows you to create sophisticated, automated workflows that span multiple tools and services, reducing manual coordination and ensuring consistent processes.

​
Quick Start

​
Creating Your First Webhook

Webhooks are configured at the project level. To create a webhook:
  1. Navigate to your project in the Speckle web app
  2. Go to Settings → Webhooks
  3. Click Create webhook
  4. Fill in the webhook configuration:
    • URL: The endpoint where webhook payloads will be sent (required)
    • Events: Select which events should trigger this webhook (required)
    • Webhook name: An optional name to help identify this webhook
    • Secret: An optional secret for verifying webhook authenticity (recommended)
  5. Click Create
You can change the webhook secret in the future, but you won’t be able to retrieve the current secret value once it’s set. Make sure to store it securely if you need it for verification.

​
Frequently Asked Questions

To get started, create your first webhook by navigating to your project’s Settings → Webhooks in the Speckle web app. You’ll need to provide a URL endpoint that can receive HTTP POST requests. See the Quick Start section above for step-by-step instructions.
Yes! Webhooks are available on any Speckle server, including app.speckle.systems and self-hosted instances. You don’t need to deploy your own server to use webhooks.
Webhooks push events to your endpoint in real-time when they occur, while polling requires you to repeatedly check the API for changes. Webhooks are more efficient, reduce server load, and provide faster notifications. Polling introduces delays and wastes resources checking for changes that may not exist.
You can create up to 100 webhooks per project. This limit helps ensure server performance and prevents abuse.
No, webhooks work with any Speckle server, including Speckle Cloud. You just need to provide a publicly accessible URL endpoint that can receive HTTP POST requests.
Webhooks are HTTP-based and designed for server-to-server communication. They’re ideal for CI/CD pipelines, automation workflows, and integrations with external services. GraphQL Subscriptions use WebSocket connections and are better suited for client applications (web apps, desktop apps) that need real-time UI updates. See the GraphQL Subscriptions documentation for more details.