Webhooks #

The Webhooks tab allows you to configure webhooks to receive real-time event data in your system or backend for the following events in Satori:

• Live Event Started: Triggered when a new run of the live event started
• Live Event Ended: Triggered when a new run of the live event ended
• Scheduled Message Sent: Triggered when a scheduled message is sent.

Webhooks in Satori is a powerful tool that allows you to automate workflows and integrate external services with your game operations. You can update related information in your backend or internal systems such as updating player stats when a live event started, ended or a message sent to a user.

Webhooks are configured as a global setting and will work for all Live Events and Messages.

Creating Webhooks #

To define a new Webhook, when you are in the Webhooks Tab, click the “Create Webhook” button on the top right. This will open the following popup and ask for some information to define the webhook.

Following information needed to create a webhook:

• URL: Your webhooks URL (e.g. https://www.your-domain.com/satoriwebhook)
• Description: Free format description that will help you to remember about the webhook.
• Custom Header: You can add a custom HTTP header for each webhook. For example, you might use it to include a unique game ID if you’re using the same webhook for multiple games.
  • Name: The name of your custom header (e.g. “game_id”)
  • Value: The value that will be sent for this custom header (e.g. “game4”)
• Listening for: You can select one or more satori events that will trigger this webhook. As mentioned above, we currently support “Live Event Started”, “Live Event Ended” and “Scheduled Message Sent” triggers.

Once you fill the required fields (URL and ‘Listening For’) and click the create button you will see your newly defined webhook in the list under the Webhooks tab.

Webhook Details #

If you click one of the webhook under the webhook page, you will open the individual details for that specific webhook.

At top of the page, you can see the details of the webbook and on the bottom, you can see the EVENTS section that will show you the details of the request and response of this particular HTTP request when you click on any of the triggered events.

Also in this page, you will be able to take following actions:

• Send test events
• Edit (under the 3 dots menu)
• Reset secret (under the 3 dots menu)
• Delete (under the 3 dots menu)

Auditing Webhook Requests #

Events section in Webhook details will help you to see all the previous attempts showing both successful and failed ones. When you click one of the attemps, the right panel will show you request header, request body and the response.

Signing Secret #

To ensure the security and integrity of webhook payloads, Satori supports the use of signatures. Each webhook has a signing secret. This secret is used to generate a signature for each payload, which is then sent along with the payload to your server. You can use this signature to verify that the payload was sent by Satori and has not been tampered with.

You can find an example code snippet in JavaScript to verify the signature.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

import express from 'express';
import bodyParser from 'body-parser';

const SIGNING_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

const hexStringToUint8Array = hexString => {
  const bytes = new Uint8Array(Math.ceil(hexString.length / 2));
  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hexString.substr(i * 2, 2), 16);
  return bytes;
};

const verifySignature = async (body, header, tolerance = 300) => {
  if (!header) return false;

  header = header.split(',').reduce((accum, x) => {
    const [k, v] = x.split('=');
    return { ...accum, [k]: v };
  }, {});

  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey("raw", encoder.encode(SIGNING_SECRET), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
  const verified = await crypto.subtle.verify("HMAC", key, hexStringToUint8Array(header.sig), encoder.encode(`${header.t}.${body}`));

  const elapsed = Math.floor(Date.now() / 1000) - Number(header.t);

  return verified && !(tolerance && elapsed > tolerance)
};

const app = express();

// Middleware to capture raw body
app.use(bodyParser.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString();
  }
}));

// ...process the webhook payload
async function processWebhookPayload(payload) { }

app.use('/webhook', async (req, res) => {
  const verified = await verifySignature(req.rawBody, req.headers['x-satori-signature'])

  if (!verified) return res.status(403).send({ message: 'Invalid signature' });

  processWebhookPayload(req.body);

  res.status(200).send({ message: 'Valid signature' });
});

app.listen(8039, () => {
  console.log(`Server running on port http://localhost:8039`);
});

If you believe your secret may have been compromised, you can reset it by selecting “Reset Secret” from the More Options menu (three dots icon).

Testing Webhooks #

To ensure your webhook is functioning as expected, click “Send Test Event” to trigger a test payload. This button will open a popup to show you to select the Webhook Event to be triggered and the contents of the request.

When a test event is sent you can see it in the EVENTS section with a TEST icon next to it.

Contents of a Webhook Request #

The webhook request body consists of 3 main parts:

• “id”: unique identifier for the request.
• “data”: information about the event triggered. Details provided for each event type below.
• “event”: name of the Satori event the webhook triggered for.

Live Event Started & Ended #

For those events, you can find an example of the request body below:

{
  "id": "ec65eb00-4546-4004-8045-2e262651defd",
  "data": {
    "id": "57b0ef5d-fbfb-49f3-bb85-0bc20509bc22",
    "name": "test-event",
    "start_time_sec": 1728998280,
    "duration_sec": 360,
    "reset_cron": "* * * * *",
    "run_start": 1729854480,
    "run_end": 1729854510
  },
  "event": "LIVE_EVENT_STARTED"
}

Under the “data” object, you will see:

• “id”: the unique identifier of this live event.
• “name”: name of the live event.
• “start_time_sec”: start time of the live event as unix timestamp in seconds.
• “duration_sec”: duration of the live event in seconds.
• “reset_cron”: reset expression of the live event as defined in the live event.
• “run_start”: start time of this run of the live event as unix timestamp in seconds.
• “run_end”: end time of this run of the live event as unix timestamp in seconds.

Scheduled Message Sent #

For this events, you can find an example of the request body below:

{
  "id": "9b8401bc-9c85-445c-94fd-06da9ead7e6e",
  "data": {
    "messages": [
      {
        "id": "39b1abac-59f7-4bcb-a815-22029142a0f1",
        "identity_id": "00000000-0000-0000-0000-000000000001",
        "title": "Attention!",
        "payload": "Jack, the world needs your help!",
        "image_url": "",
        "send_time_sec": 1736354260
      },
      {
        "id": "8a9f8033-8669-40da-acf4-ba7499ecdcd6",
        "identity_id": "00000000-0000-0000-0000-000000000003",
        "title": "Attention!",
        "payload": "Paul, the world needs your help!",
        "image_url": "",
        "send_time_sec": 1736354260
      }
    ],
    "message_schedule": {
      "id": "55e39305-bd09-4a89-877f-e7262fb2a506"
    },
    "live_event": {
      "id": "83e6e6d1-ad06-4ca3-8b0d-c1f01bbf935f",
      "value": "{}"
    }
  },
  "event": "SCHEDULED_MESSAGE_SENT"
}

Under the “data” object, you will see:

• “messages”: Array of messages sent with each array containing:
  • “id”: unique message instance (uuid).
  • “identity_id”: identity id of the player receiving the message.
  • “title”: title of the message.
  • “payload”: contents of the message.
  • “image_url”: URL of the image in the message if exists.
  • “send_time_sec”: the time the message should be sent.
• “message_schedule”: Object containing the information about the message’s schedule such as schedule ID.
• “live_event”: Object containing the linked live event information for the message.