Webhooks

Documentation for webhooks

For organization webhook events, check the docs, here.

Configuration

To enable webhooks, configure the WEBHOOK_URL and WEBHOOK_SECRET environment variables. Once enabled, the URL specified will start receiving the following events:

Platform Events

USER_REGISTER_SUCCESS

Triggered whenever a user registration is successful.

• user_id: The unique identifier of the registered user.

• user_email: The email address of the registered user.

Sample Payload:

{
  "version": 1,
  "event": "USER_REGISTER_SUCCESS",
  "payload": {
    "user_id": "1234abcd",
    "user_email": "[e-mail]"
  }
}

APOLLO_MIGRATE_INIT

Triggered when graph migration is initiated.

actor_id (optional): The identifier of the actor initializing the migration

Sample Payload:

{
  "version": 1,
  "event": "APOLLO_MIGRATE_INIT",
  "payload": {
    "actor_id": "user5678"
  }
}

APOLLO_MIGRATE_SUCCESS

Triggered when graph migration succeeds.

• federated_graph: An object representing the federated graph details.

  • id: The unique identifier of the federated graph.

  • name: The name of the federated graph.

• actor_id (optional): The identifier of the actor initializing the migration.

Sample Payload:

{
  "version": 1,
  "event": "GRAPH_MIGRATE_SUCCESS",
  "payload": {
    "federated_graph": {
      "id": "graph123",
      "name": "MainGraph",
      "namespace": "default"
    },
    "actor_id": "user5678"
  }
}

Verification

To ensure the webhook data is coming from a trusted source and hasn’t been tampered with during transit, we employ HMAC signatures. When setting up a webhook, you provide a secret. This secret is used to compute a signature that is sent along with each webhook request.

The header containing this signature is X-Cosmo-Signature-256.

Verification Example

To verify the webhook request, you need to compute the HMAC signature on your server and compare it to the signature in the X-Cosmo-Signature-256 header.

Here’s an example in Node.js:

import crypto from 'crypto';

function verifySignature(body, receivedSignature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return computedSignature === receivedSignature;
}

// Usage:
const isVerified = verifySignature(JSON.stringify(req.body), req.headers['x-cosmo-signature-256'], YOUR_SECRET);