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.
- Open the Business Communications Developer Console and sign in with your RBM partner Google Account.
- Click your agent.
- Click Integrations.
- For Webhook, click Configure.
- For Webhook endpoint URL, enter your webhook URL beginning with "https://".
- Note your
clientToken
value. You need it to verify that messages you receive are coming from Google. Configure your webhook to accept a
POST
request with the specifiedclientToken
parameter and send a200 OK
response with the plain text value of thesecret
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, ifclientToken
is correct, return a200 OK
response with1234567890
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); });
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:
- Extract the message's
X-Goog-Signature
header. This is a hashed, base64-encoded copy of the message body payload. - Base-64-decode the RBM payload in the
message.body
element of the request. - 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.
- 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.