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);

Message handling

Returning anything other than 200 OK from a webhook is considered a delivery failure.

Developers must be mindful that sending messages at high rates will generate webhook notifications at high rates and must design their code to ensure they can consume notifications at the expected rate. It is important that developers consider situations that may cause failure responses - including 500 responses from their web container, timeouts or upstream failures. Thing to consider include:

  • Ensure your DDoS protections are configured to handle the expected rate of webhook notifications.
  • Ensure resources such as database connection pools don't run out and produce timeouts or 500 responses.

Behaviour on delivery failure

RBM uses a backoff and retry mechanism when it receives a response other than 200 OK from a webhook call. RBM will increase the time it waits between retries up to a maximum of 600 seconds. Retires will continue for 7 days, after which the message will be dropped.

Implications of agent-level webhooks

RBM queues messages for a partner on one queue. Where a partner is using agent-level webhooks, it is important to bear in mind that the failure of one webhook will impact delivery to other webhooks. Webhooks belonging to other agents will be called during the backoff period of a failed message but as failed messages queue up for retry, overall delivery rates will fall and other agents will be impacted.

It is important that developers understand this model and code accordingly - as far as possible, accepting messages and queueing them for processing to minimise the opportunity of returning a failure.

Next steps

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