Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Orchestrate. With webhooks, your app can know when something happens in Orchestrate, such as a payment being created or updated.

Registering webhooks

To register a webhook, provide a URL in your app that accepts POST requests and can handle the webhook payload for supported events.

Set up webhooks in the Orchestrate dashboard under Developer » Webhooks. Name your webhook and optionally add a description. After creation, you'll receive a webhook secret—use this to verify requests from Orchestrate. For details on how to verify the webhook request using the secret, see the verifying webhook requests section.

You can add multiple webhook URLs, for example, separate ones for staging and development, to test integrations without affecting production.

Consuming webhooks

When your app receives a webhook request from Orchestrate, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a payment, etc.

{
  "id": "event_123456",
  "type": "payment.created",
  "payload": {
    "id": "payment_123456",
    // ...
  }
}

In the example above, a payment was created, and the payload type is a payment.

Event types

{
  "api_version": "1",
  "type": "payment.succeeded",
  "payload": {
    "id": "payment_123456",
    "amount": 1000,
    "currency": "USD",
    "status": "completed",
    "customer": {
      "email": "john.doe@example.com",
      "name": "John Doe"
    },
    "metadata": {
      "order_id": "order_123456"
    }
  },
  "timestamp": "2025-05-18T12:00:00Z"
}

Verifying webhook requests

To know for sure that a webhook was, in fact, sent by Orchestrate instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named X-Signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC SHA-256 hash of the request payload hashed using your webhook secret key.

Here is an example of how to verify the signature in your application:

const signature = '<x-signature-header>'
const payload = '{"webhook":"payload"}'
const secret = process.env.ORCHESTRATE_WEBHOOK_SECRET

const hash = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('base64')

if (
  crypto.timingSafeEqual(
    Buffer.from(hash, 'base64'),
    Buffer.from(signature, 'base64'),
  )
) {
  console.log('Request is verified')
} else {
  console.log('Request could not be verified')
}

If your generated signature matches the X-Signature header, you can be sure that the request was truly coming from Orchestrate. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Orchestrate. Don't commit your secret webhook key to GitHub!