Webhooks

Who can use this: Roles that can manage integrations.

A webhook sends an HTTPS request to your server when something happens in PraismaHub. Each request is signed so you can check that it came from us.

Add an endpoint

1. Open Settings, then Integrations, then Webhooks.

2. Enter a name and your URL. The URL must use https and cannot be a private network address.

3. Choose the scope: the whole workspace, which receives events from every organization, or one organization.

4. Select the events you want and save.

5. Copy the secret. It is shown when you create the endpoint and when you rotate it.

Events

• Organizations: organization.created, organization.updated, organization.deleted

• Users: user.invited, user.created, user.updated, user.deleted

• Security: security.password_changed, security.two_factor_enabled, security.two_factor_disabled

• CMS types: cms.type.created, cms.type.updated, cms.type.deleted

• CMS content: cms.content.created, cms.content.updated, cms.content.deleted, cms.content.published, cms.content.unpublished, cms.content.archived, cms.content.restored

• Inbox: inbox.message.received, inbox.comment.received

• Orders: commerce.order.created, commerce.order.paid, commerce.order.shipped, commerce.order.delivered, commerce.order.cancelled, commerce.order.refunded

• Customers: commerce.customer.created

• Quotes: commerce.quote.requested, commerce.quote.sent, commerce.quote.accepted, commerce.quote.declined

• Bookings: commerce.booking.confirmed, commerce.booking.cancelled, commerce.booking.unfulfillable

• Stock and reviews: commerce.inventory.low_stock, commerce.review.submitted, commerce.review.replied

• Leads: lead.submission.created, sent through the Webhook action of a lead workflow.

What you receive

A JSON body with id, event, test, organization_id, data and created_at. The headers are:

• X-Praisma-Signature

• X-Praisma-Timestamp

• X-Praisma-Event

• X-Praisma-Delivery

Check the signature

The signature looks like t=1794265722,v1=abc123. v1 is the HMAC-SHA256, in hex, of the timestamp, a dot and the raw body, keyed with your secret exactly as shown. Use the raw body, before any JSON parsing.

const crypto = require('crypto');

function isValid(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(parts.t + '.' + rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

The timestamp is new on every attempt, so you can reject old requests.

Retries

Any 2xx answer counts as delivered. Redirects are not followed.

• By default there are 5 attempts with a 10 second timeout. The first wait is 10 seconds and it doubles each time, up to 600 seconds.

• You can set 1 to 20 attempts and a timeout of 1 to 60 seconds.

• A 4xx answer is not retried, except 408 and 429.

• An endpoint is turned off after 10 failed deliveries in a row. Set this to 0 to never turn it off.

Test and troubleshoot

• Send a test from the endpoint. It only sends events the endpoint subscribes to, and test is true in the body.

• Open the logs to see each attempt and its answer.

• Rotate the secret if it may have leaked, then update your server.

Related

• Content API and authentication

• Lead forms and workflows