Prismatic Event Webhooks

A webhook is a way for an application to provide other applications with real-time information. This article covers outbound event webhooks in Prismatic - notifications you receive when events occur in your Prismatic account.

This article covers outbound webhooks

Here, we're talking about Prismatic-specific events that occur (e.g. an integration in Prismatic was published or a customer in Prismatic was updated), and you want an external app to know about that change.

If you're interested in incoming webhooks for your integrations (e.g. A Salesforce contact was updated and you want your integration's trigger to be notified), see What is a webhook?.

Why use Prismatic event webhooks?

Prismatic event webhooks allow you to stay informed about important changes and activities within your Prismatic platform. Here are some common use cases:

• Audit Trail: Keep a record of all platform changes for compliance and tracking purposes
• Monitoring & Alerting: Get notified when critical events occur, such as integrations being published or instances being deployed
• Integration with External Systems: Send Prismatic events to your monitoring tools, logging systems, or custom applications
• Real-time Updates: Receive immediate notifications instead of manually checking the web app or querying the Prismatic API

How event webhooks work

When an event occurs in your Prismatic organization, Prismatic sends a POST request to your configured webhook URL with a JSON payload containing details about the event.

Your application receives the webhook, validates it (optionally using HMAC signatures), and processes the event according to your business logic.

To get started with event webhooks, see Configuring event webhooks.

Webhook payload structure

When an event occurs, Prismatic sends a POST request to your webhook URL with a JSON payload. Here's an example of what the payload looks like:

{
  "integration": {
    "id": "SW50ZWdyYXRpb246ZWM5YzViM2EtZjNhNy00MDliLTllM2QtODA3MDAxNDVlNWU0",
    "name": "Slack Integration",
    "description": "Get alerts in Slack when new contacts are created",
    "category": "Communication",
    "has_unpublished_changes": false,
    "version_number": 6,
    "created_at": "2025-08-21T20:22:54.828609+00:00",
    "updated_at": "2025-08-21T20:22:54.828609+00:00"
  },
  "customer": null,
  "parent_integration": null,
  "user": {
    "id": "VXNlcjoyMzZkMDA3ZS0zZGIxLTQ4MWItOTMyNS0zMjhhYTE0OTY5MDA=",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "event_type": "integration.published",
  "timestamp": "2025-08-21T20:22:57.855591+00:00",
  "organization_id": "T3JnYW5pemF0aW9uOmJjYjE0NjEzLTNjZTItNGQ0MC04OTZmLTIyNTZiNjcyYTllYw==",
  "webhook_id": "c1e226a7-8d13-4d46-98d9-a99a2d6bdb37"
}

Payload fields

Field	Description
event_type	The type of event that occurred (e.g., integration.published)
timestamp	When the event occurred (ISO 8601 format)
webhook_id	Unique identifier for the webhook that sent this notification
organization_id	Your Prismatic organization ID
user	Information about the user who triggered the event (if applicable)
integration	Integration details (for integration-related events)
customer	Customer details (for customer-related events)
instance	Instance details (for instance-related events)
workflow	Workflow details (for workflow-related events)
component	Component details (for component-related events)
connection	Connection details (for connection-related events)
alert_monitor	Alert monitor details (for alert-related events)
alert_group	Alert group details (for alert group events)
log_stream	Log stream details (for log stream events)
user_level_config	User Level Config details (for user level config events)
performed_by	The user who performed the action, when it differs from user

Available event types

Prismatic provides comprehensive coverage of platform events. Here's a complete list of available event types:

Instance events

Event	ID	Emitted when
Instance Created	instance.created	A new instance is created via createInstance.
Instance Updated	instance.updated	An instance's stored configuration is modified via updateInstance or updateInstanceConfigVariables. Does not fire when only toggling enabled - see instance.enabled / instance.disabled - or when the only change was one user's user-level configuration - see user_level_config.deployed.
Instance Deleted	instance.deleted	An instance is removed via deleteInstance.
Instance Deployed	instance.deployed	An instance is successfully deployed via deployInstance. Configuration changes do not auto-deploy - this event is the signal that the running instance reflects the new config.
Instance Enabled	instance.enabled	An instance is activated (for example, updateInstance with enabled: true).
Instance Disabled	instance.disabled	An instance is deactivated (for example, updateInstance with enabled: false).

User Level Config events

User Level Configuration (ULC) lets each of a customer's users supply their own credentials and settings on top of an instance's shared configuration. One instance is deployed to the customer, and each user then provides their own configuration through the config wizard. These events track that per-user activity.

Event	ID	Emitted when
User Level Config Deployed	user_level_config.deployed	A user finishes providing their user-level configuration for an instance, through the config wizard, createUserLevelConfig, or updateInstanceConfigVariables with configMode: USER and configComplete: true.
User Level Config Deleted	user_level_config.deleted	A user's user-level configuration is removed via deleteUserLevelConfig, or the instance it belongs to is deleted.

user_level_config.deployed fires every time a user completes their configuration, not only the first time - the same way instance.deployed fires on every deploy. To count first-time activations, deduplicate on the user_level_config.id in the payload.

Two things deliberately do not emit these events: redeploying an instance, and upgrading an instance to a new integration version. Both re-apply every user's configuration, but no user changed anything. Deleting a user does not emit user_level_config.deleted either - subscribe to user.deleted for that.

Customer events

Event	ID	Description
Customer Created	customer.created	Triggered when a new customer is added to your platform
Customer Updated	customer.updated	Triggered when customer information is modified
Customer Deleted	customer.deleted	Triggered when a customer is removed from the platform

User events

Event	ID	Description
User Created	user.created	Triggered when a new user account is created
User Updated	user.updated	Triggered when user profile information is modified
User Deleted	user.deleted	Triggered when a user account is removed

Integration events

Event	ID	Description
Integration Created	integration.created	Triggered when a new integration is created
Integration Updated	integration.updated	Triggered when integration configuration is modified
Integration Deleted	integration.deleted	Triggered when an integration is removed
Integration Published	integration.published	Triggered when an integration is published to the marketplace

Workflow events

Event	ID	Description
Workflow Created	workflow.created	Triggered when a new workflow is created within an integration
Workflow Updated	workflow.updated	Triggered when workflow configuration is modified
Workflow Deleted	workflow.deleted	Triggered when a workflow is removed
Workflow Published	workflow.published	Triggered when a workflow is published
Workflow Enabled	workflow.enabled	Triggered when a workflow is activated
Workflow Disabled	workflow.disabled	Triggered when a workflow is deactivated

Component events

Event	ID	Description
Component Deleted	component.deleted	Triggered when a custom component is removed
Component Published	component.published	Triggered when a component is published to the marketplace

Connection events

Event	ID	Description
Connection Updated	connection.updated	Triggered when connection configuration is modified
Connection Deleted	connection.deleted	Triggered when a connection is removed

Alert & monitoring events

Event	ID	Description
Alert Monitor Created	alert_monitor.created	Triggered when a new alert monitor is configured
Alert Monitor Updated	alert_monitor.updated	Triggered when alert monitor settings are modified
Alert Monitor Deleted	alert_monitor.deleted	Triggered when an alert monitor is removed
Alert Group Created	alert_group.created	Triggered when a new alert group is created
Alert Group Updated	alert_group.updated	Triggered when alert group configuration is modified
Alert Group Deleted	alert_group.deleted	Triggered when an alert group is removed

Log stream events

Event	ID	Description
Log Stream Created	log_stream.created	Triggered when a new log stream is configured
Log Stream Updated	log_stream.updated	Triggered when log stream settings are modified
Log Stream Deleted	log_stream.deleted	Triggered when a log stream is removed

OAuth2 events

Event	ID	Description
OAuth2 Authorization Completed	oauth2.authorization_completed	Triggered when OAuth2 authorization is successfully completed
OAuth2 Authorization Failed	oauth2.authorization_failed	Triggered when OAuth2 authorization fails
OAuth2 Token Refreshed	oauth2.token_refreshed	Triggered when an OAuth2 token is successfully refreshed
OAuth2 Token Refresh Failed	oauth2.token_refresh_failed	Triggered when OAuth2 token refresh fails

System events

Event	ID	Description
Test	webhook.test	Triggered when testing a webhook configuration

Event relationships

Several event types relate to the same underlying object but represent different state changes. Understanding how they relate helps you choose the right subset to subscribe to.

instance.updated vs instance.deployed

These are distinct signals, and most consumers want both:

• instance.updated fires when an instance's stored configuration changes (via updateInstance or updateInstanceConfigVariables).
• instance.deployed fires when you run the deployInstance mutation and the running instance begins using the new configuration.

Configuration changes do not automatically deploy. After updating config variables via the API, you must call deployInstance for the runtime to pick them up. If you're using webhooks to know when to bust a cache of deployed config, listen to instance.deployed.

user_level_config.deployed vs instance.deployed

Both signal that something became live, but at different scopes:

• instance.deployed fires when the instance itself is deployed via deployInstance. It is an organization- or customer-level event.
• user_level_config.deployed fires when a single end user finishes their own configuration on an instance that is already deployed. The instance's deployed_version and last_deployed_at do not change.

A change to one user's configuration does not emit instance.updated, because the instance itself did not change. If you are tracking end-user activations of a user-level-configured integration, user_level_config.deployed is the event to subscribe to.

connection.updated vs OAuth2 events

connection.updated fires only when a connection's stored configuration is modified via the updateOAuth2Connection mutation. It does not fire for OAuth2 token refreshes or user-initiated authorization flows:

• OAuth2 token refreshes emit oauth2.token_refreshed or oauth2.token_refresh_failed.
• User-completed OAuth2 authorization emits oauth2.authorization_completed or oauth2.authorization_failed.

Credential state and connection-configuration state change through separate mechanisms and surface as separate events. Subscribing only to instance.updated or connection.updated will not notify you of credential changes.

instance.updated is not a superset of all instance changes

A common misconception is that instance.updated fires for every event that affects an instance. It does not. For complete coverage of instance-related state, subscribe to:

• instance.created, instance.updated, instance.deleted for configuration lifecycle
• instance.deployed for runtime state
• instance.enabled / instance.disabled for activation state
• OAuth2 events and connection.updated for credential and connection state on the connections an instance uses
• user_level_config.deployed / user_level_config.deleted for per-user configuration on user-level-configured instances

Payload contents

Instance webhook payloads identify the instance (ID, name, timestamps, deployed version, enabled state) but do not include the config variables themselves or a diff of what changed. If you need the new config values after an instance.updated event, query the instance by ID through the GraphQL API.

Next steps

• Configure event webhooks to start receiving notifications
• Prismatic Insider: Subscribing to Events with Prismatic's API and Event Webhooks
• Example Node.js Express Webhook Receiver