Set Webhook Secret - API Reference

Sets the shared secret used to sign every webhook we send you. Your server uses the same value to confirm a request is authentic — see Verifying webhooks for how.

You choose the value; there is no generate-a-secret endpoint. Use a CSPRNG rather than inventing one by hand:

openssl rand -hex 32

Calling this endpoint again replaces the previous secret. The account has one secret, shared by every monitor and every webhook URL.

POST https://api.socialdata.tools/user/webhook/secret

Headers

Authorization string required

Authorization Bearer header containing your SocialData API key

Example: Bearer YOUR_API_KEY

Body

secret string required

The shared secret used to sign webhook requests. Maximum 256 characters. Store it somewhere your webhook handler can read it, and treat it like a password

Example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Code Examples

curl -X POST "https://api.socialdata.tools/user/webhook/secret" \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{"secret": "YOUR_WEBHOOK_SECRET"}'

const API_KEY = 'YOUR_API_KEY_HERE';
const webhookSecret = 'YOUR_WEBHOOK_SECRET';

fetch('https://api.socialdata.tools/user/webhook/secret', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    },
    body: JSON.stringify({ secret: webhookSecret })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));

import requests

API_KEY = 'YOUR_API_KEY_HERE'
webhook_secret = 'YOUR_WEBHOOK_SECRET'

url = 'https://api.socialdata.tools/user/webhook/secret'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

payload = {'secret': webhook_secret}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code}")
    print(response.text)

$API_KEY = 'YOUR_API_KEY_HERE';
$webhook_secret = 'YOUR_WEBHOOK_SECRET';

$url = "https://api.socialdata.tools/user/webhook/secret";

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(['secret' => $webhook_secret]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $API_KEY",
        "Content-Type: application/json",
        "Accept: application/json"
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);

curl_close($ch);

Example Responses

{
  "status": "success",
  "message": "Webhook secret updated"
}

{
  "message": "The secret field is required.",
  "errors": {
    "secret": [
      "The secret field is required."
    ]
  }
}

Response Codes

200 OK - request succeeded
422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)

Rotating the secret

New deliveries are signed with the new value as soon as the change takes effect. Deliveries already in flight were signed with the old one, so a strict handler will reject them.

If dropped events matter, accept either secret for a few minutes:

Deploy a handler that treats a request as valid if it verifies against the old secret or the new one.
Call this endpoint with the new secret.
Once traffic has settled, remove the old secret from the handler.