IO Signature

This page describes implementing IO Signature and toggling it on

IO Signature is an optional feature that prevents clients from onboarding phone numbers without authorization from the partner platform.

We recommend partners use IO signatures to enhance their platform security.

Implementing IO signatures requires adding a new server endpoint.

IO Signature Implementation

Server-only

IO signature generation must only be done server-side.

Do not generate the signature on the frontend - this will leak the platform secret, allowing for unauthorized phone number onboarding attempts, as well as risking webhook URL's security.

If the platform secret has leaked, regenerate it on the 360Dialog Hub by following instructions here.

Get Platform Secret

Get an existing platform secret, or generate a new one by following the instructions here.

Prepare String to Sign

Prepare the string to sign with the platform secret. The string is the partner's ID and timestamp now in UNIX seconds separated by a pipe character. Example:

{partnerId}|{timestampSeconds}

If the partner's ID is aAbBcCPA, and the timestamp is 1775653748, the string to sign would look like:

aAbBcCPA|1775653748

Avoid caching

Caching this string preparation step, or the signing step below, is not recommended (e.g. generating every N minutes).

Replay protection prevents reusing the same signature across multiple onboarding attempts.

Compute Signature

The signature must be computed using HMAC-SHA512. Sign the string prepared in Step 2 using the platform secret acquired in Step 1.

Below are code samples for Python, Node.js, and PHP.

# io_signature.py

import os
import time
import hmac
import hashlib

partner_id = "Your partner ID here"

# Platform secret should be passed as an environment variable as best practice
secret = os.getenv("PLATFORM_SECRET")

def generate_signature(partner_id: str, secret: str) -> dict:
    if secret is None or secret.trim() == "":
        raise Exception("ERROR: No platform secret provided")
        
    timestamp = int(time.time())
    message = f"{partner_id}|{timestamp}"
    
    signature = hmac.new(
        secret.encode("utf-8"),
        message.encode("utf-8"),
        hashlib.sha512
    ).hexdigest()

    return {
        "timestamp": timestamp,
        "signature": signature,
    }

// io_signature.js

import crypto from "crypto";

const partnerId = "Your partner ID here";

// Partner secret should be passed as an environment variable as best practice
const secret = process.env.PLATFORM_SECRET;

export function generateSignature() {
	if (!secret || !secret.trim()) {
		throw Error("ERROR: No platform secret provided");
	};
	
	const timestamp = Math.floor(Date.now() / 1000);
	const message = `${partnerId}|${timestamp}`;
	const signature = crypto
		.createHmac("sha512", secret)
		.update(message)
		.digest("hex");
	return { signature, timestamp };
}

// io_signature.php

<?php

function generateSignature(): array
{
    $partnerId = "Your partner ID here";

    // Platform secret should be passed as an environment variable as best practice
    $secret = getenv("PLATFORM_SECRET");

    $timestamp = time();
    $message = $partnerId . "|" . $timestamp;

    $signature = hash_hmac("sha512", $message, $secret);

    return [
        "timestamp" => $timestamp,
        "signature" => $signature,
    ];
}

Serve Signature and Timestamp

Partner's server must generate the signature and timestamp at each authenticated request, and serve them to users before they start onboarding a phone number.

If the app is rendered client-side, the server must have a REST endpoint for requesting a signature and timestamp.

If the app is rendered server-side, the server can also ship the signature and timestamp in the page's HTML.

Below are REST API endpoint samples for Python, Node.js, and PHP, each serving at GET /api/sign_io.

Authentication

These code samples do not cover authentication.

Make sure to implement authentication into the server, and authenticate all requests made to this endpoint. Skipping this step breaks security benefits of IO signatures.

# server.py

import os
import time
import hmac
import hashlib
from flask import Flask, jsonify
from io_signature import generate_signature # Sample shown in Step 3

app = Flask(__name__)

@app.get("/api/sign_io")
def signature():
    return jsonify(generate_signature())

// server.js

import express from "express";
import crypto from "crypto";
import dotenv from "dotenv";
import { generateSignature } from "./io_signature.js"; // Sample shown in Step 3

dotenv.config();

const app = express();

app.get("/api/sign_io", (req, res) => {
  res.json(generateSignature());
});

app.listen(3000);

Enable IO Signature

Open 360Dialog Hub

Click here to open 360Dialog Hub.

Open Integration Page

Navigate to the Integration page by clicking here.

Test IO Signature

Get a signature and timestamp from your server's signature endpoint, exampled under IO Signature Implementation.

Click Test in the UI, then paste the signature and timestamp, and finally click Test.

Toggle IO Signature

Enable IO Signature by clicking the toggle next to IO Signature if:

The test in Step 3 was successful,
The frontend successfully requests a signature from the backend,
And frontend correctly passes the IO signature + timestamp to the integrated onboarding link.

Enabling this toggle will enforce a valid IO signature + timestamp on all onboarding attempts.

IO Security Measures

When IO Signature is enabled, 360Dialog protects against integrated onboarding link staleness and reuse.

Link Staleness

Signatures older than 24 hours are automatically rejected.

Suggestion

Store in the frontend when the signature was received. When the user attempts to start onboarding, check if the signature was received more than 24 hours ago; if true, get a new signature.

Link Reuse

Replay protection is active for 48 hours per used signature.

When a signature is first used to attempt integrated onboarding, any further attempts to use the signature are blocked. As a result, users cannot use the same integrated onboarding link to perform multiple onboarding attempts.

Suggestion

Issue a new signature + timestamp per onboarding attempt.

Examples of Using IO Signatures

Direct URL

https://local.360dialog.io/onboarding/Mr2ww7PA?redirect_url=http%3A%2F%2Flocalhost%3A1234%2F&plan_selection=basic&flow=partner_activation&io_signature=02260b46b339f154a76bb543c5c6537afb5ec9dd83536d6afaa8e61aca83968bffadb20b8cc3257c48f5079f29ad988eadbe7ffa54669b36b69cf7876ec22815&io_timestamp=1782083643

Connect button Setup:

<ConnectButton
partnerId={PARTNER_ID}
label="Create WABA"
callback={object => console.log(object)}
version="v2"
queryParameters={{
io_signature:
'02260b46b339f154a76bb543c5c6537afb5ec9dd83536d6afaa8e61aca83968bffadb20b8cc3257c48f5079f29ad988eadbe7ffa54669b36b69cf7876ec22815',
io_timestamp: '1782083643',
}}
/>

Vanillajs/HTML:

<dialog-connect-button
  id="connectBtn"
  partner-id="YOUR_PARTNER_ID"
  label="Connect WhatsApp Business"
></dialog-connect-button>
<script>
  // Fetch a fresh signature on page load
  fetch('https://your-server.com/api/sign_io')
    .then(res => res.json())
    .then(payload => {
      const btn = document.getElementById('connectBtn');
      btn.setAttribute('io-signature', payload.signature);
      btn.setAttribute('io-timestamp', payload.timestamp);
    });
  window.addEventListener('dialog-connect-callback', event => {
    console.log('client ID:', event.detail.client);
    console.log('channel IDs:', event.detail.channels);
  });
</script>

After the Embedded signup, if the signature has been manipulated or expired within 24 hours, then the FB callback fails and returns this error:

PreviousIntegrated Onboarding NextUsing Direct Link

Last updated 21 days ago

Was this helpful?