Prismatic Event Webhooks

A webhook is a way for an application to provide other applications with real-time information. This article covers how to set up and use outbound event webhooks in Prismatic, so you can be notified of events that 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

Setting up event webhooks

To set up or manage your event webhooks, first navigate to the Event Webhooks tab in your Prismatic organization settings. Click +Event Webhook to configure a new webhook, or click an existing webhook to modify it.

Fill in the required information

Name: A descriptive name for your webhook (e.g., "Production Monitoring")
URL: The endpoint where webhooks will be sent
Secret: (Optional) An HMAC secret key for verifying webhook signatures
Description: Additional context about the webhook's purpose
Is Enabled: Toggle to enable or disable the webhook

Next, select the events that should trigger this webhook

You can select individual events or use category checkboxes to select all events of a certain type
Common selections include:
- Instance lifecycle events (created, updated, deployed)
- Integration changes (published, updated)
- Customer management events
- Alert monitor

Test your webhook
- Use the Test Webhook button to verify your endpoint is working
- Check that you receive the test payload at your endpoint
Save and enable
- Click Save to create the webhook
- Ensure the Is Enabled toggle is turned on

Testing Prismatic event webhooks

Use the Test Webhook button in the Prismatic UI to:

Verify your endpoint is accessible
Confirm the payload format is correct
Test your webhook processing logic
Validate authentication and security measures

When you click Test Webhook, your endpoint will receive a webhook.test event with a payload that looks like

{
  "message": "This is a test webhook event from Prismatic.",
  "webhook_endpoint": {
    "id": "V2ViaG9va0VuZHBvaW50OmJiNGVjYTIzLWI5NzgtNDU1Mi05MDljLTI5YmRlMzZjZTYxMQ==",
    "name": "Notify Acme of Changes"
  },
  "user": {
    "id": "VXNlcjoyMzZkMDA3ZS0zZGIxLTQ4MWItOTMyNS0zMjhhYTE0OTY5MDA=",
    "email": "john.doe@example.io",
    "name": "John Doe"
  },
  "event_type": "webhook.test",
  "timestamp": "2025-08-21T20:21:40.405396+00:00",
  "organization_id": "T3JnYW5pemF0aW9uOmJjYjE0NjEzLTNjZTItNGQ0MC04OTZmLTIyNTZiNjcyYTllYw==",
  "webhook_id": "bdea273d-2500-42a2-854b-5189c3f66cfa"
}

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)

Available event types

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

Instance Events

Event	ID	Description
Instance Created	`instance.created`	Triggered when a new integration instance is created
Instance Updated	`instance.updated`	Triggered when an instance's configuration is modified
Instance Deleted	`instance.deleted`	Triggered when an instance is removed from the platform
Instance Deployed	`instance.deployed`	Triggered when an instance is successfully deployed
Instance Enabled	`instance.enabled`	Triggered when an instance is activated
Instance Disabled	`instance.disabled`	Triggered when an instance is deactivated

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

Prismatic event webhook security

If you set a Secret when configuring your webhook, Prismatic will use it to generate an HMAC SHA-256 signature for each webhook request. The signature will be sent as a header, x-webhook-signature in the form sha256=<signature>.

This allows you to ensure that the webhook request is coming from Prismatic and has not been tampered with.

For example, suppose you receive the following webhook event payload:

Example webhook event payload
{"message":"This is a test webhook event from Prismatic.","webhook_endpoint":{"id":"V2ViaG9va0VuZHBvaW50OjEwNTI1MjE3LTE4NDMtNGRiNC04YjYyLTgwZTdmOTc5OGEzZA==","name":"Testing"},"user":{"id":"VXNlcjozNDkwNjA3MC0wMjRmLTQxNzMtYjYxMy1mN2I0MWFmYmEwNDM=","email":"john.doe@example.com","name":"John Doe"},"event_type":"webhook.test","timestamp":"2025-10-08T14:13:05.914923+00:00","organization_id":"T3JnYW5pemF0aW9uOjQ0ZjkyMTlkLWU0ZGEtNGEwZi04ZmNhLWJkZmJlNTdiMzBjNA==","webhook_id":"4c79940b-b166-41cb-8b45-944e25b480f3"}

If your secret is set to my-secret-key-abc-123, the x-webhook-signature header would contain

Example x-webhook-signature header
sha256=88563276df8a665d1e57bf8a05c2c2432ff80b583297082b768fb06f173e0b59

Example of verifying signatures with Express

In this example Express app, we verify the request signature using Node.js's crypto module before processing the webhook event:

Verifying webhook signatures in Node.js with Express
import express from "express";
import { createHmac } from "node:crypto";

const PORT = 3000;
const PRISMATIC_SIGNING_SECRET = "my-secret-key-abc-123";

const app = express();

app.post("/my-webhook-endpoint", express.raw({ type: "*/*" }), (req, res) => {
  // Get HMAC signature from header and compare it to the one we generate
  const signatureHeader = req.headers["x-webhook-signature"];
  const signature = createHmac("sha256", PRISMATIC_SIGNING_SECRET)
    .update(req.body)
    .digest("hex");

  // If the signatures don't match, return a 401
  if (signatureHeader !== `sha256=${signature}`) {
    console.warn("Rejecting request with invalid HMAC signature");
    return res.status(401).send({ error: "Invalid signature" });
  }

  // Parse the event request and handle the event
  const payload = JSON.parse(req.body.toString());
  switch (payload.event_type) {
    case "webhook.test":
      console.log("Got a test webhook");
      break;
    case "instance.created": {
      console.log(
        `Instance (${payload.instance.id}) created from integration (${payload.integration.name}) for customer ${payload.customer.external_id}`,
      );
      break;
    }
    default:
      console.warn(`Unhandled event type: ${req.body.toString()}`);
  }
  res.status(200).send({ received: true });
});

app.listen(PORT, () => {
  console.log(`Example webhook receiver listening on port ${PORT}`);
});

Similar strategies can be used in other programming languages and frameworks.

Webhook retry

If a Prismatic event webhook request fails (e.g., due to a network error or a non-200 HTTP response), Prismatic will automatically retry the request up to three times after 100, 200, and 400ms.

If more than 25 webhook requests have failed within one minute, the webhook will be disabled for 5 minutes. All events that accumulate during that duration will be sent once the webhook is re-enabled after 5 minutes.

Troubleshooting

Webhook not receiving events

Verify the webhook is enabled
Check that the correct event types are selected
Ensure your endpoint is accessible and responding with 2xx status codes

Missing events

Confirm the event types you've selected
Check if the events actually occurred in Prismatic
Verify your webhook configuration is saved

Authentication errors

Ensure your endpoint accepts POST requests
Check that you're not requiring authentication that Prismatic can't provide
Verify your endpoint can handle the webhook payload format

Why use Prismatic event webhooks?​

Setting up event webhooks​

Testing Prismatic event webhooks​

Webhook payload structure​

Payload fields​

Available event types​

Instance Events​

Customer Events​

User Events​

Integration Events​

Workflow Events​

Component Events​

Connection Events​

Alert & Monitoring Events​

Log Stream Events​

OAuth2 Events​

System Events​

Prismatic event webhook security​

Example of verifying signatures with Express​

Webhook retry​

Troubleshooting​