Webhooks: Difference between revisions

From CasperTech Wiki
Jump to navigation Jump to search
(Created page with "New for 2018, our Webhook system is a beefed-up version of CasperVend's ANS notification system. This is an advanced system which requires programming knowledge. It's designed...")
 
No edit summary
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
New for 2018, our Webhook system is a beefed-up version of CasperVend's ANS notification system. This is an advanced system which requires programming knowledge. It's designed to reliably send events to servers you manage.
New for 2018, our Webhook system is a beefed-up version of CasperVend's ANS notification system. This is an advanced system which requires programming knowledge. It's designed to reliably send events to server(s) under your control.


= <span style="color:#00528c">Benefits</span> =
= <span style="color:#00528c">Benefits</span> =


: * Reliable. If your server goes offline, we'll keep sending until it goes through (though see the caveats below)
: * Increased reliability. If your server goes offline, we'll keep sending until it goes through (though see the caveats below)
: * Not just for vendor sales, but can also notify for marketplace sales, updates and redeliveries
: * Not just for vendor sales, but can also notify for marketplace sales and redeliveries
: * Not just for CasperVend, but will be rolled out for CasperLet, CasperSafe, CasperUpdate, etc. in the future.
: * JSON encoded so can be read by nearly all backend frameworks
: * JSON encoded so can be read by nearly all backend frameworks
: * In the event of a failure to reach your endpoint, we will notify your avatar by IM (after 5 attempts).
: * In the event of a failure to reach your endpoint, we will notify your avatar by IM (after 5 attempts).
: * SL Marketplace notifications include the matched CasperVend product ID (zero if not associated).
= <span style="color:#00528c">Events Currently Tracked</span> =
: * Product purchase inworld
: * SL Marketplace purchase
=== Tracking Coming Soon For ===
----
: * Redeliveries
: * Update Delivery
(This list will be added to and corrected as features and additional event tracking are built in.)


= <span style="color:#00528c">Caveats</span> =
= <span style="color:#00528c">Caveats</span> =
Line 13: Line 26:
: * Because of the retry mechanism, your code must be prepared to accept duplicate requests.
: * Because of the retry mechanism, your code must be prepared to accept duplicate requests.
: * We send events in date order, so if an early event fails, you won't receive any later events until your endpoint responds correctly.
: * We send events in date order, so if an early event fails, you won't receive any later events until your endpoint responds correctly.
: * Your endpoint must respond within 5 seconds.
: * Your endpoint must respond within 3 seconds.
 
= <span style="color:#00528c">Getting Help</span> =
 
This is an advanced feature; you are expected to know how to write and debug your own scripts, so we won't help you do that.
 
However, if you need a different kind of help - or if you think something is wrong at our end, do a '''[[CasperVend_2/Getting_Help#How_Can_I_Get_Help.3F | ticket to Casper.]]''' The rest of the support staff are NOT scripters and CANNOT assist you with this.


= <span style="color:#00528c">Example Code</span> =
= <span style="color:#00528c">Example Code</span> =
Line 22: Line 41:


<syntaxhighlight lang="sql" line='line'>
<syntaxhighlight lang="sql" line='line'>
CREATE DATABASE IF NOT EXISTS `webhooks` /*!40100 DEFAULT CHARACTER SET utf8 */;
CREATE DATABASE IF NOT EXISTS `webhooks`;
USE `webhooks`;
USE `webhooks`;


Line 36: Line 55:


== PHP ==
== PHP ==
This code assumes that you have a database created using the SQL above.


<syntaxhighlight lang="php" line='line'>
<syntaxhighlight lang="php" line='line'>
Line 45: Line 66:


define('ENABLE_DEBUG', true);
define('ENABLE_DEBUG', true);
define('DEBUG_EMAIL', 'debug@caspertech.co.uk');
define('DEBUG_EMAIL', 'your@email.address');


define('DATABASE_HOST', '127.0.0.1');
define('DATABASE_HOST', '127.0.0.1');
Line 132: Line 153:
         // If you're not using fastcgi, PLEASE don't keep the remote
         // If you're not using fastcgi, PLEASE don't keep the remote
         // server waiting while you do your event processing. Remember
         // server waiting while you do your event processing. Remember
         // you must respond within 5 seconds.
         // you must respond within 3 seconds.


         // Run a script via a cron job to process your incoming events.
         // Run a script via a cron job to process your incoming events.
Line 155: Line 176:
     }
     }
}
}
</syntaxhighlight>
== Discord ==
Would you like to see your CasperVend and Marketplace sales appear in your Discord server? Here's an example script!
<syntaxhighlight lang="php" line='line'>
<?php
define('WEBHOOK_SALT', '{{YOUR_WEBHOOK_SALT}}');
define('DISCORD_WEBHOOK_URL', '{{YOUR_DISCORD_WEBHOOK_URL}}');
define('ENABLE_DEBUG', false);
define('DEBUG_EMAIL', 'your@email.address');
// Get the raw POST data
$postData = file_get_contents("php://input");
// Integrity check
if (!isset($_SERVER['HTTP_X_CASPER_WEBHOOK_INTEGRITY_HASH']) || $_SERVER['HTTP_X_CASPER_WEBHOOK_INTEGRITY_HASH'] !== sha1($postData) || !isset($_SERVER['HTTP_X_CASPER_WEBHOOK_VERIFY_HASH']))
{
    http_response_code(400);
    die('Corruption detected');
}
// Now we check if the request is actually intended for us
$hashCheck = sha1(sha1($postData).":".WEBHOOK_SALT);
if ($_SERVER['HTTP_X_CASPER_WEBHOOK_VERIFY_HASH'] !== $hashCheck)
{
    http_response_code(403);
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Webhook Script Error', 'Unauthorised request');
    die('Unauthorised');
}
// By this stage we have a validated webhook event. Now decode the json
$data = json_decode($postData, true);
if ($data === false)
{
    // JSON decode failure. This should never happen since the payload is signed..
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Webhook Script Error', 'JSON decode failure');
    die('Invalid payload');
}
echo "OK";
if (function_exists('fastcgi_finish_request'))
{
    // This releases the request so Casper's servers don't have to wait for discord
    fastcgi_finish_request();
}
$timestamp = date("c", strtotime("now"));
$embed = [];
$eventType = $data['metadata']['eventType'];
if ($eventType === 'vendor_sale')
{
    if ($data['event']['flags']['luckyChair'] === TRUE)
    {
        $embed = [
            "title" => $data['event']['avatars']['purchaser']['name'] . ' won a ' . $data['event']['product']['productName'] . ' from a Lucky Chair!',
            "color" => 15746887
        ];
    }
    else
    {
        if ($data['event']['flags']['midnightMadness'] === TRUE)
        {
            $embed = [
                "title" => $data['event']['avatars']['purchaser']['name'] . ' won a ' . $data['event']['product']['productName'] . ' from a Midnight Madness board!',
                "color" => 16426522
            ];
        }
        else
        {
            if ($data['event']['flags']['gatcha'] === TRUE)
            {
                $embed = [
                    "title" => $data['event']['avatars']['purchaser']['name'] . ' won a ' . $data['event']['product']['productName'] . ' from a gacha!',
                    "color" => 4437377
                ];
            }
            else
            {
                $embed = [
                    "title" => $data['event']['avatars']['purchaser']['name'] . ' bought a ' . $data['event']['product']['productName'],
                    "color" => 7506394
                ];
            }
        }
    }
    $embed['image'] = [
        "url" => "https://caspervend.casperdns.com/img.php?u=".$data['event']['product']['texture']."&g=SLIFE"
    ];
    $embed['description'] = '**Paid:** L$' . $data['event']['money']['gross']. "\n".
        '**Received:** L$' . $data['event']['money']['received']. "\n".
        '**Location:** ' . $data['event']['vendor']['location']. "\n";
    if ($data['event']['avatars']['recipient']['uuid'] !== $data['event']['avatars']['purchaser']['uuid'])
    {
        $embed['description'] = "**As a gift for " . $data['event']['avatars']['recipient']['name'] . "**\n" . $embed['description'];
    }
    if ($data['event']['flags']['giftCard'] === true || $data['event']['flags']['giftCardV3'] === true) {
        $embed['description'] .= "*This was a gift card purchase*\n";
    }
}
else if ($eventType === 'marketplace_sale')
{
    $embed = [
        "title" => $data['event']['PayerName'] . ' bought a ' . $data['event']['ItemName'] . ' from the Marketplace',
        "color" => 814798,
        "description" => "**Paid** L$" .$data['event']['PaymentGross']. "\n**Fee** L$" . $data['event']['PaymentFee']
    ];
    if ($data['event']['ReceiverKey'] !== $data['event']['PayerKey'])
    {
        $embed['description'] = "**As a gift for " . $data['event']['ReceiverName'] . "**\n" . $embed['description'];
    }
}
else
{
    $embed = [
        "title" => 'Received unsupported event of type ' . $eventType,
        "color" => 7506394
    ];
}
$json_data = json_encode([
    "username" => "Store",
    "embeds" => [
        $embed
    ]
], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE );
$ch = curl_init( DISCORD_WEBHOOK_URL );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-type: application/json'));
curl_setopt( $ch, CURLOPT_POST, 1);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $json_data);
curl_setopt( $ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt( $ch, CURLOPT_HEADER, 0);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec( $ch );
if (ENABLE_DEBUG)
{
    mail(DEBUG_EMAIL, 'Discord Webhook Response', $response);
}
curl_close( $ch );
</syntaxhighlight>
</syntaxhighlight>

Latest revision as of 08:52, 20 July 2021

New for 2018, our Webhook system is a beefed-up version of CasperVend's ANS notification system. This is an advanced system which requires programming knowledge. It's designed to reliably send events to server(s) under your control.

Benefits

* Increased reliability. If your server goes offline, we'll keep sending until it goes through (though see the caveats below)
* Not just for vendor sales, but can also notify for marketplace sales and redeliveries
* Not just for CasperVend, but will be rolled out for CasperLet, CasperSafe, CasperUpdate, etc. in the future.
* JSON encoded so can be read by nearly all backend frameworks
* In the event of a failure to reach your endpoint, we will notify your avatar by IM (after 5 attempts).
* SL Marketplace notifications include the matched CasperVend product ID (zero if not associated).

Events Currently Tracked

* Product purchase inworld
* SL Marketplace purchase

Tracking Coming Soon For


* Redeliveries
* Update Delivery

(This list will be added to and corrected as features and additional event tracking are built in.)

Caveats

* If we can't get through to your server, we will try again on an exponential backoff. The first 5 attempts happen every minute, but after that the length of time doubles for each attempt.
* If we still cannot get through to your server after 43 attempts (approximately 24 hours), we will drop all pending notifications and disable your webhook.
* Because of the retry mechanism, your code must be prepared to accept duplicate requests.
* We send events in date order, so if an early event fails, you won't receive any later events until your endpoint responds correctly.
* Your endpoint must respond within 3 seconds.

Getting Help

This is an advanced feature; you are expected to know how to write and debug your own scripts, so we won't help you do that.

However, if you need a different kind of help - or if you think something is wrong at our end, do a ticket to Casper. The rest of the support staff are NOT scripters and CANNOT assist you with this.

Example Code

MySQL

Should work with any modern MySQL daemon. Tested with MariaDB 10.2.12

CREATE DATABASE IF NOT EXISTS `webhooks`;
USE `webhooks`;

CREATE TABLE IF NOT EXISTS `events` (
  `eventID` char(36) NOT NULL,
  `received` datetime NOT NULL DEFAULT current_timestamp(),
  `processed` tinyint(1) unsigned NOT NULL DEFAULT 0,
  `data` mediumblob DEFAULT NULL,
  PRIMARY KEY (`eventID`),
  KEY `processed` (`processed`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

PHP

This code assumes that you have a database created using the SQL above.

<?php

// Configuration options

define('WEBHOOK_SALT', 'YOUR SALT HERE');

define('ENABLE_DEBUG', true);
define('DEBUG_EMAIL', 'your@email.address');

define('DATABASE_HOST', '127.0.0.1');
define('DATABASE_USER', 'webhooks');
define('DATABASE_PASSWORD', 'somepassword');
define('DATABASE_DATABASE', 'webhooks');

// Get the raw POST data
$postData = file_get_contents("php://input");

// Integrity check
if (!isset($_SERVER['HTTP_X_CASPER_WEBHOOK_INTEGRITY_HASH']) || $_SERVER['HTTP_X_CASPER_WEBHOOK_INTEGRITY_HASH'] !== sha1($postData) || !isset($_SERVER['HTTP_X_CASPER_WEBHOOK_VERIFY_HASH']))
{
    http_response_code(400);
    die('Corruption detected');
}

// Connect to the database
$dsn = 'mysql:dbname='.DATABASE_DATABASE.';host='.DATABASE_HOST;

try
{
    $dbh = new PDO($dsn, DATABASE_USER, DATABASE_PASSWORD);
} catch (PDOException $e)
{
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Webhook Script Error', 'Database connection failed');
    die('Database connection failed');
}

// Now we check if the request is actually intended for us

$hashCheck = sha1(sha1($postData).":".WEBHOOK_SALT);

if ($_SERVER['HTTP_X_CASPER_WEBHOOK_VERIFY_HASH'] !== $hashCheck)
{
    http_response_code(403);
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Webhook Script Error', 'Unauthorised request');
    die('Unauthorised');
}

// By this stage we have a validated webhook event. Now decode the json

$data = json_decode($postData, true);

if ($data === false)
{
    // JSON decode failure. This should never happen since the payload is signed..
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Webhook Script Error', 'JSON decode failure');
    die('Invalid payload');
}


// Get the event ID
$eventID = $data['metadata']['eventID'];

// Insert the event into the database.

// IMPORTANT: To avoid duplicates, make sure that eventID is a primary key.

$stmt = $dbh->prepare("INSERT IGNORE INTO `events` (`eventID`, `received`, `data`) VALUES (:eventID, NOW(), :data)");

if (!$stmt)
{
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Database error', var_export($dbh->errorInfo(), true));
}

if (!$stmt->execute([
    ":eventID" => $eventID,
    ":data" => $postData
]))
{
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Database statement error', var_export($stmt->errorInfo(), true));
}


if ($stmt->rowCount() == 0)
{
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL,'duplicate ans event', $postData);
    // Duplicate event
    die();
}
else
{
    if (!function_exists('fastcgi_finish_request'))
    {
        // If you're not using fastcgi, PLEASE don't keep the remote
        // server waiting while you do your event processing. Remember
        // you must respond within 3 seconds.

        // Run a script via a cron job to process your incoming events.

        die();
    }
    fastcgi_finish_request();


    // Process any unprocessed events.  You can do this here, or offload it into a cron job or something.

    $stmt = $dbh->query("SELECT `data`,`eventID` FROM `events` WHERE `processed` = 0 ORDER BY `received` ASC");
    while($row = $stmt->fetch(\PDO::FETCH_ASSOC))
    {
        // Do your processing

        // blah blah blah

        // All done? Mark the event as processed
        $substmt = $dbh->prepare("UPDATE `events` SET `processed` = 1 WHERE `eventID` = :id");
        $substmt->execute([":id" => $row['eventID']]);
    }
}


Discord

Would you like to see your CasperVend and Marketplace sales appear in your Discord server? Here's an example script!

<?php
define('WEBHOOK_SALT', '{{YOUR_WEBHOOK_SALT}}');
define('DISCORD_WEBHOOK_URL', '{{YOUR_DISCORD_WEBHOOK_URL}}');
define('ENABLE_DEBUG', false);
define('DEBUG_EMAIL', 'your@email.address');

// Get the raw POST data
$postData = file_get_contents("php://input");

// Integrity check
if (!isset($_SERVER['HTTP_X_CASPER_WEBHOOK_INTEGRITY_HASH']) || $_SERVER['HTTP_X_CASPER_WEBHOOK_INTEGRITY_HASH'] !== sha1($postData) || !isset($_SERVER['HTTP_X_CASPER_WEBHOOK_VERIFY_HASH']))
{
    http_response_code(400);
    die('Corruption detected');
}

// Now we check if the request is actually intended for us

$hashCheck = sha1(sha1($postData).":".WEBHOOK_SALT);

if ($_SERVER['HTTP_X_CASPER_WEBHOOK_VERIFY_HASH'] !== $hashCheck)
{
    http_response_code(403);
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Webhook Script Error', 'Unauthorised request');
    die('Unauthorised');

}

// By this stage we have a validated webhook event. Now decode the json

$data = json_decode($postData, true);

if ($data === false)
{
    // JSON decode failure. This should never happen since the payload is signed..
    if (ENABLE_DEBUG) mail(DEBUG_EMAIL, 'Webhook Script Error', 'JSON decode failure');
    die('Invalid payload');
}



echo "OK";
if (function_exists('fastcgi_finish_request'))
{
    // This releases the request so Casper's servers don't have to wait for discord
    fastcgi_finish_request();
}

$timestamp = date("c", strtotime("now"));

$embed = [];

$eventType = $data['metadata']['eventType'];
if ($eventType === 'vendor_sale')
{
    if ($data['event']['flags']['luckyChair'] === TRUE)
    {
        $embed = [
            "title" => $data['event']['avatars']['purchaser']['name'] . ' won a ' . $data['event']['product']['productName'] . ' from a Lucky Chair!',
            "color" => 15746887
        ];
    }
    else
    {
        if ($data['event']['flags']['midnightMadness'] === TRUE)
        {
            $embed = [
                "title" => $data['event']['avatars']['purchaser']['name'] . ' won a ' . $data['event']['product']['productName'] . ' from a Midnight Madness board!',
                "color" => 16426522
            ];
        }
        else
        {
            if ($data['event']['flags']['gatcha'] === TRUE)
            {
                $embed = [
                    "title" => $data['event']['avatars']['purchaser']['name'] . ' won a ' . $data['event']['product']['productName'] . ' from a gacha!',
                    "color" => 4437377
                ];
            }
            else
            {
                $embed = [
                    "title" => $data['event']['avatars']['purchaser']['name'] . ' bought a ' . $data['event']['product']['productName'],
                    "color" => 7506394
                ];
            }
        }
    }

    $embed['image'] = [
        "url" => "https://caspervend.casperdns.com/img.php?u=".$data['event']['product']['texture']."&g=SLIFE"
    ];

    $embed['description'] = '**Paid:** L$' . $data['event']['money']['gross']. "\n".
        '**Received:** L$' . $data['event']['money']['received']. "\n".
        '**Location:** ' . $data['event']['vendor']['location']. "\n";

    if ($data['event']['avatars']['recipient']['uuid'] !== $data['event']['avatars']['purchaser']['uuid'])
    {
        $embed['description'] = "**As a gift for " . $data['event']['avatars']['recipient']['name'] . "**\n" . $embed['description'];
    }

    if ($data['event']['flags']['giftCard'] === true || $data['event']['flags']['giftCardV3'] === true) {
        $embed['description'] .= "*This was a gift card purchase*\n";
    }
}
else if ($eventType === 'marketplace_sale')
{
    $embed = [
        "title" => $data['event']['PayerName'] . ' bought a ' . $data['event']['ItemName'] . ' from the Marketplace',
        "color" => 814798,
        "description" => "**Paid** L$" .$data['event']['PaymentGross']. "\n**Fee** L$" . $data['event']['PaymentFee']
    ];

    if ($data['event']['ReceiverKey'] !== $data['event']['PayerKey'])
    {
        $embed['description'] = "**As a gift for " . $data['event']['ReceiverName'] . "**\n" . $embed['description'];
    }
}
else
{
    $embed = [
        "title" => 'Received unsupported event of type ' . $eventType,
        "color" => 7506394
    ];
}


$json_data = json_encode([
    "username" => "Store",

    "embeds" => [
        $embed
    ]

], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE );


$ch = curl_init( DISCORD_WEBHOOK_URL );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-type: application/json'));
curl_setopt( $ch, CURLOPT_POST, 1);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $json_data);
curl_setopt( $ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt( $ch, CURLOPT_HEADER, 0);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec( $ch );

if (ENABLE_DEBUG)
{
    mail(DEBUG_EMAIL, 'Discord Webhook Response', $response);
}

curl_close( $ch );