Webhooks

A webhook allows your application to receive real-time notifications when specific events occur. Webhooks can be configured through the PORTOS BackOffice application. For each webhook, you can define the following options:

• URL: address where the events will be delivered

• Secret: optional string that is used to create JSON payload signature.

• Resource filter: specifies list of resources (e.g. tickets, article categories, ...) for which notification will be sent.

When an event is triggered, the PORTOS API sends an HTTP POST request to the specified URL, carrying the event data as a JSON payload. It is essential that the external application hosting the URL can handle these HTTP POST requests to process the event data effectively.

Testing Webhook Deliveries

1. In your browser, navigate to https://smee.io

2. Click Start a new channel. Smee.io will generate a unique Webhook Proxy URL for you.

3. Copy the full URL under "Webhook Proxy URL".

4. Open PORTOS BackOffice application.

5. Navigate to System > Extensions > Webhooks (or Systém > Rozšírenia > Webhooky if using the Slovak version).

6. Create a new webhook and paste the copied URL from Smee.io into the Address (Adresa) field.

7. Press the Save (Uložiť) button

8. In PORTOS BackOffice, perform an action such as creating, editing, or deleting a resource (e.g., an article category).

9. Check your Smee.io channel; the event should appear, confirming that the webhook is working correctly.

Setup an webhook using your smee.io channel URL

The reeived webhook is displayed in your smee.io channel

Validating Webhook Deliveries

To ensure the security and authenticity of webhook deliveries, users have the option to specify a "secret" when setting up a webhook. If a secret is defined, every webhook request from your app will include an HTTP header named X-PORTOS-WEBHOOK-SIGNATURE. This header contains an HMACSHA256 signature of the JSON payload, generated using the secret. External applications can use this signature to validate that the webhook requests are genuinely from your app and have not been tampered with.

Example Implementations

To implement HMAC verification in your app, please refer to examples below. Examples are using following variables:

• jsonPayload: The content of the HTTP request body that contains the event data in JSON format.

• receivedSignature : The value of the X-PORTOS-WEBHOOK-SIGNATURE HTTP header, which contains the HMACSHA256 signature sent by the PORTOS API.

• secret: The secret key specified in webhook settings, used to generate the signature.

C#

using System.Security.Cryptography;
using System.Text;

public bool ValidateWebhookSignature(string jsonPayload, string receivedSignature, string secret)
{
    // Convert the secret to a byte array
    var secretKey = Encoding.UTF8.GetBytes(secret);

    // Create HMACSHA256 using the secret key
    using (var hmac = new HMACSHA256(secretKey))
    {
        // Compute the hash of the JSON payload
        var payloadBytes = Encoding.UTF8.GetBytes(jsonPayload);
        var computedHash = hmac.ComputeHash(payloadBytes);

        // Convert the computed hash to a hex string
        var computedSignature = BitConverter.ToString(computedHash).Replace("-", "").ToLower();

        // Compare the computed signature with the received signature
        return computedSignature == receivedSignature.ToLower();
    }
}

PHP

function validateWebhookSignature($jsonPayload, $receivedSignature, $secret)
{
    // Compute the HMACSHA256 hash of the JSON payload using the secret
    $computedHash = hash_hmac('sha256', $jsonPayload, $secret);

    // Compare the computed hash with the received signature
    return hash_equals($computedHash, $receivedSignature);
}

TypeScript

import * as crypto from 'crypto';

function validateWebhookSignature(jsonPayload: string, receivedSignature: string, secret: string): boolean {
    // Create HMACSHA256 hash using the secret key
    const hmac = crypto.createHmac('sha256', secret);
    hmac.update(jsonPayload);

    // Compute the hash as a hex string
    const computedSignature = hmac.digest('hex');

    // Compare the computed signature with the received signature
    return computedSignature === receivedSignature.toLowerCase();
}

Example Hash calculation

Here’s an example of how to calculate the SHA256 hash for a webhook using the provided secret and JSON content:

Secret: my-secret-key

JSON content:

{"id":"c32314f8-39c2-4d03-864e-201586637657","version":"1.0","event":"portos.resources.changed","data":{"user":{"name":"Majiteľ","userName":"999","featureName":null,"deviceName":"BackOffice"},"resourceName":"articleCategories","action":"Updated","resource":{"label":"PIV","description":"Pivá","customerDescription":"","courseNumber":null,"color":"#FF9800","sortHint":null,"tags":[],"ordering":null}}}

Resulting SHA256 hash: 06324bd73f157373a4a678320a014d8c3db4c2e07d8a6177ecdf233b9f07d3f0

Webhook payload

Data models

The webhook content follows this data structure:

WebhookPayloadDto

Name	Type	Description
id	string	Unique webhook identifier (GUID v4 format), generated by PORTOS API.
version	string	Indicates version of webhook payload. Currently fixed to "1.0"
event	string	Name of event. Currently, only resource changed events are delivered, so values is fixed to "portos.resources.changed"
data	WebhookResourceChangedContentDto	Based on value of "event" field, content may vary.

WebhookResourceChangedContentDto

Name	Type	Description
user	UserInfoIdentity?	Information about user that triggers the resource change.
action	string	Name of action that represents the resource change. Supported values: created, updated or deleted.
resourceName	string	Name of resource, e.g. ticket, articleCategory, ...
resource	object	The resource that has been created/updated/deleted. Based on value of "resourceName" field, content may vary (e.g. for "ticket", content is Ticket.

UserInfoIdentity

Name	Type	Description
name	string	Display name of user.
userName	string	Unique user identifier.
featureName	string	Name of feature (specified for "virtual" users only, e.g. user representing some Portos extension).
deviceName	string	Unique name of the device on which the user operates.

Webhook Payload Example

Please note that the actual payload does not include JSON indentation.

{
    "id": "c32314f8-39c2-4d03-864e-201586637657",
    "version": "1.0",
    "event": "portos.resources.changed",
    "data":
    {
        "user":
        {
            "name": "Majiteľ",
            "userName": "999",
            "featureName": null,
            "deviceName": "BackOffice"
        },
        "resourceName": "articleCategories",
        "action": "Updated",
        "resource":
        {
            "label": "PIV",
            "description": "Pivá",
            "customerDescription": "",
            "courseNumber": null,
            "color": "#FF9800",
            "sortHint": null,
            "tags":
            [],
            "ordering": null
        }
    }
}