Assinatura de Requisições

Como segurança adicional, você pode usar assinaturas em todas as solicitações para e da nossa API. O uso de assinaturas é opcional. No entanto, se uma assinatura for enviada, ela deve ser válida.

Ao enviar solicitações para nossa API, você gera uma assinatura que envia com seus dados. Ao receber, o webhook de entrada contém a assinatura e todos os campos que você precisa para criar a assinatura em sua aplicação, a fim de verificar a correspondência das duas assinaturas e, assim, a precisão do webhook.

Com esta assinatura, pode-se garantir que

a solicitação realmente vem da fonte correta,
a solicitação não foi alterada durante o trânsito,
as solicitações não sejam interceptadas e repetidas posteriormente.

A assinatura deve conter obrigatoriamente alguns dados, como o timestamp, a URL de destino, um chamado Nonce e os dados enviados.

Estrutura da Assinatura

Para criar uma assinatura, são necessários os seguintes dados:

Valor	Descrição
Nonce	Uma string aleatória, composta por 32 caracteres alfanuméricos. Deve ser única para cada solicitação.
Timestamp	O momento da solicitação como Unix Timestamp, não deve ter mais de 30 segundos
Método HTTP	O método de solicitação HTTP, por exemplo, POST ou GET
URL de Destino	A URL completa para a qual a solicitação será enviada
Conteúdo da Solicitação	Hash MD5 do conteúdo da solicitação

Zur Generierung der Signatur wird der SHA256 HMAC Algorithmus mit dem Signierschlüssel Ihres Accounts verwendet. Den Schlüssel finden Sie in Ihrem Login im Bereich Entwickler in den API Einstellungen.

Estrutura da sequência de caracteres a ser assinada

A sequência de caracteres a ser assinada deve ser construída da seguinte forma:

STRING_TO_SIGN =
  Zeitstempel + \n +
  Nonce + \n +
  HTTPMethode + \n +
  ZielURL + \n +
  ContentBodyMD5

Se você enviar, por exemplo, esta requisição:

POST https://gateway.seven.io/api/sms

{"to": "49170123456789", "text": "Hello World! :-)", "from": "seven"}

A sequência de caracteres a ser assinada seria construída da seguinte forma:

STRING_TO_SIGN =
  1634641200
  fpPRhAd1s8GXacfR39mWqKPynmmXfJnc
  POST
  https://gateway.seven.io/api/sms
  62dd06ffb3101dc2456517b177b744ae

Valor	Explicação
1634641200	O timestamp atual no momento do envio da requisição, aqui 19.10.2021 às 13:00:00
fpPRhAd1s8GXacfR39mWqKPynmmXfJnc	Uma string gerada aleatoriamente com 32 caracteres
POST	O método HTTP utilizado
https://gateway.seven.io/api/sms	A URL de destino
62dd06ffb3101dc2456517b177b744ae	MD5( {"to": "49170123456789", "text": "Hello World! :-)", "from": "seven"} )

Criação da assinatura

Para criar a assinatura, utilize o algoritmo SHA256 HMAC em conjunto com o Signierschlüssel do seu account.

printf "${STRING_TO_SIGN}" | openssl dgst -sha256 -hmac "${SIGNING_SECRET}"

Implementações semelhantes estão disponíveis na maioria das linguagens de programação comuns, como por exemplo em PHP:

$signature = hash_hmac('sha256', $STRING_TO_SIGN, $SIGNING_SECRET);

Envio da Assinatura

A assinatura, o nonce e o timestamp devem ser enviados nos cabeçalhos HTTP da solicitação.

Name
X-Signature
Type
string
Description
A assinatura gerada por você
Name
X-Timestamp
Type
integer
Description
O timestamp no qual a assinatura foi criada
Name
X-Nonce
Type
string
Description
O nonce criado por você

Exemplos

Script Bash com curl e openssl

#!/bin/bash

# Ihre API Daten
API_KEY="IHR_API_SCHLÜSSEL"
SIGNING_SECRET="IHR_SIGNIER_SCHLÜSSEL"

# Zufälligen Nonce erstellen
NONCE=$(openssl rand -hex 32)

# Zeitstempel
TIMESTAMP=$(date +%s)

# Daten des Requests
HTTP_VERB="POST"
URL="https://gateway.seven.io/api/sms"
CONTENT_BODY="{ \"to\": \"0170123456789\", \"text\": \"Hello World! :-)\", \"from\": \"seven.io\" }"

# Signatur erstellen
CONTENT_BODY_MD5=$(printf "${CONTENT_BODY}" | md5sum | awk '{print $1}')
STRING_TO_SIGN=$(printf "${TIMESTAMP}
${NONCE}
${HTTP_VERB}
${URL}
${CONTENT_BODY_MD5}")
SIGNATURE=$(printf "${STRING_TO_SIGN}" | openssl dgst -sha256 -hmac "${SIGNING_SECRET}" | sed 's/^.*= //')

# Request absenden
curl -X $HTTP_VERB $URL \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Nonce: $NONCE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  -d "${CONTENT_BODY}"

Script PHP

# Ihre API Daten
$key = 'IHR_API_SCHLÜSSEL';
$secret = 'IHR_SIGNIER_SCHLÜSSEL';

# Zufälligen Nonce erstellen 
$nonce = bin2hex(random_bytes(16)); 

# Zeitstempel
$timestamp = time();

# Daten des Requests
$http_verb = 'POST';

$content_body = json_encode([
  'to' => '49170123456789',
  'text' => 'Hello World! :-)',
  'from' => 'seven.io',
]);

$url = 'https://gateway.seven.io/api/sms';

# Signatur erstellen
$StringToSign = [$timestamp, $nonce, $http_verb, $url, md5($content_body)];
$StringToSign = implode(PHP_EOL, $StringToSign);

$hash = hash_hmac('sha256', $StringToSign, $secret);

# Header setzen
$headers = [
  'X-Signature: ' . $hash,
  'X-Api-Key: ' . $key,
  'X-Timestamp:' . $timestamp,
  'X-Nonce:' . $nonce,
  'Content-type: application/json',
  'Accept: application/json'
];

# Request absenden
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $content_body);

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

echo $result;