Webhooks

A webhook is a partner-created HTTPS callback that specifies how your agent should respond to messages and events. Once you configure your webhook, you can start receiving messages and events.

Partner webhooks and agent webhooks

You can configure your webhook either at the partner level or at the agent level.

  • Your partner webhook applies to every agent you maintain. If your agents have similar behavior, or if you only have one agent, use the partner webhook.
  • Agent webhooks apply to individual agents. If you operate multiple agents with distinct behavior, you can set a different webhook for each agent.

If you've configured both a partner webhook and an agent webhook, the agent webhook takes precedence on its specific agent, while the partner webhook applies to any agents that don't have their own webhook.

Configure an agent webhook

You receive messages sent to your agent at your partner webhook. If you want messages for a specific agent to arrive at a different webhook instead, set an agent webhook.

  1. Open the Business Communications Developer Console and sign in with your RBM partner Google Account.
  2. Click your agent.
  3. Click Integrations.
  4. For Webhook, click Configure.
  5. For Webhook endpoint URL, enter your webhook URL beginning with "https://".
  6. Note your clientToken value. You need it to verify that messages you receive are coming from Google.

  7. Configure your webhook to accept a POST request with the specified clientToken parameter and send a 200 OK response with the plain text value of the secret parameter as the response body.

    For example, if your webhook receives a POST request with the following body content

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    then your webhook should confirm the clientToken value and, if clientToken is correct, return a 200 OK response with 1234567890 as the response body:

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. In the Developer Console, click Verify. When RBM verifies your webhook, the dialog closes.

Verify incoming messages

Because webhooks can receive messages from any senders, you should verify that Google sent incoming messages before processing message content.

To verify that Google sent a message you received, follow these steps:

  1. Extract the message's X-Goog-Signature header. This is a hashed, base64-encoded copy of the message body payload.
  2. Base-64-decode the RBM payload in the message.body element of the request.
  3. Using your webhook's client token (which you specified when you set up your webhook) as a key, create a SHA512 HMAC of the bytes of the base-64 decoded message payload and base64-encode the result.
  4. Compare the X-Goog-Signature hash with the hash you created.
    • If the hashes match, you've confirmed that Google sent the message.

    • If the hashes don't match, check your hashing process on a known-good message.

      If your hashing process is working correctly and you receive a message that you believe was fraudulently sent to you, contact us.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

Next steps

Once you configure your webhook, your agent can receive messages from your test devices. Send a message to validate your setup.