Send leads to a webhook

You can send your Riddle leads and responses automatically to your marketing software or data warehouse for each person who completes your lead generation form. Here's some more information about webhooks and APIs.

Add a webhook

  1. Set up a URL for a webhook on your web server.
  2. For testing purposes we recommend creating a free webhook on as this will allow you to inspect the data Riddle sends to the webhook.
  3. In Riddle, go to PUBLISH and click on Save and connect data.
    save and connect data
  4. Under Add integrations, find Webhook, and click on ADD.
  5. Enter the URL of your webhook endpoint into the Webhook URL field and click on CONTINUE.
    webhook url
  6. A test lead will be sent automatically but you can retest by clicking on SEND.
  7. Click on CONTINUE.
  8. You will see all the Riddle events on your test webhook and, when then in use, on your server.

Process the webhook

Please note that the code above is very specific to a Riddle with one question and one form field. You need to adjust your code to capture the data from your Riddle. By using you will get a good overview of all the data your Riddle sends to the webhook.


// read the raw payload from the request
$rawPayload = file_get_contents('php://input');

if (!$rawPayload) {
    die('No payload received');

file_put_contents(__DIR__.'/payload.json', $rawPayload); // optional: save the payload to a file for debugging

// now, let's decode the payload
$payload = json_decode($rawPayload, true);

// ======
// == Extract data points from the payload

// basic information about the lead itself
$uniqueId = $payload['uniqueId'];
$riddleId = $payload['riddleId'];
$identifier = $payload['identifier'];
$version = $payload['version'];
$createdAt = $payload['createdAt'];

// information about the Riddle
$riddleTitle = $payload['data']['riddle'][0]['title'];
$riddleBlockId = $payload['data']['riddle'][0]['blockId'];
$riddleValue = $payload['data']['riddle'][0]['value'][0];

// information about the form; in our case we only have *ONE* form field.
$formTitle = $payload['data']['form'][0]['title'];
$formBlockId = $payload['data']['form'][0]['blockId'];
$formFieldId = $payload['data']['form'][0]['fieldId'];
$formValue = $payload['data']['form'][0]['value'];

// information about the result
$resultBlockId = $payload['data']['result']['blockId'];
$resultTitle = $payload['data']['result']['title'];
$resultScore = $payload['data']['result']['score'];
$resultMaxScore = $payload['data']['result']['maxScore'];

// NOW: do whatever you want with the data, for example save it to a MySQL database
$sql = "INSERT INTO [...]";