Plusius · Integration guide

Webhook integration

Webhooks notify your system when events occur, such as a payment completing or failing. Use them to keep your records up to date without repeatedly checking for changes.

Use your platform configuration. The events and payloads available to you depend on your integration. Confirm the relevant event types, payload fields and environment-specific settings with your Plusius integration contact.

Before you start

Provide an HTTPS endpoint

Host an HTTPS endpoint that Plusius can reach and that accepts POST requests. Share its URL with your Plusius integration contact for the environment you are setting up.

Request a signing secret

Ask Plusius for your shared webhook signing secret. Store it securely on your server and use it to verify each notification before processing it.

Integration at a glance

  1. 1ConfigureProvide your endpoint URL and obtain your signing secret.
  2. 2ReceiveRead the original request body and the ms-signature header.
  3. 3VerifyCheck the versioned HMAC-SHA256 signature before using the payload.
  4. 4AcknowledgeRespond to Plusius promptly after accepting a valid webhook.
  5. 5Process safelyUpdate your system and handle repeated notifications without duplicating work.

1. Configure your endpoint

Choose an HTTPS URL on your system and give it to Plusius. The path is your choice; this is only an example:

POSThttps://<your-domain>/webhooks/plusius

Plusius sends the JSON payload in the request body and its signature in the ms-signature request header. The request content type is application/json.

Keep the original body. Verify the signature against the exact bytes received, before parsing or reserializing the JSON. Even a change to whitespace can produce a different signature.

2. Verify each signature

Plusius calculates an HMAC-SHA256 signature using your secret and the original JSON body. The signature is a hexadecimal value in the ms-signature header.

v1,F1D2A6C3869EE32F40748151922757614A1FD17B30726492326FBEDF897ABFEF

This is an example header, not a signature you should expect for every webhook.

  1. Read the complete ms-signature header and the raw body bytes.
  2. Check that the header starts with the supported version prefix, v1,. Remove that prefix to obtain the hexadecimal signature.
  3. Compute HMAC-SHA256 over the raw body using the UTF-8 bytes of your shared secret as the key.
  4. Decode the hexadecimal signature and compare it with your result using a fixed-time comparison. Hexadecimal letter case does not matter.
  5. Only process the payload if the signatures match. Reject missing, malformed, unsupported-version or mismatched signatures without processing the payload.
Protect your secret. Keep it out of source code and customer-facing applications. Do not log the secret or full webhook payloads.
View the .NET 10 signature verification example

This helper verifies the version and signature. It does not read the HTTP request, persist the webhook or implement your business processing.

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

public static class WebhookSignature
{
    public static bool IsValid(
        string? signatureHeader,
        ReadOnlySpan<byte> rawBody,
        string secretKey)
    {
        if (string.IsNullOrWhiteSpace(secretKey) ||
            signatureHeader is null ||
            !signatureHeader.StartsWith("v1,", StringComparison.Ordinal))
        {
            return false;
        }

        string hexSignature = signatureHeader[3..];
        if (hexSignature.Length != 64)
        {
            return false;
        }

        byte[] receivedSignature;
        try
        {
            receivedSignature = Convert.FromHexString(hexSignature);
        }
        catch (FormatException)
        {
            return false;
        }

        byte[] key = Encoding.UTF8.GetBytes(secretKey);
        byte[] expectedSignature = HMACSHA256.HashData(key, rawBody);

        return CryptographicOperations.FixedTimeEquals(
            expectedSignature,
            receivedSignature);
    }
}

Read the body in an ASP.NET Core endpoint

In this excerpt, request is an HttpRequest and secretKey is loaded from your secure configuration. Ensure your endpoint limits request sizes before buffering the body.

using var buffer = new MemoryStream();
await request.Body.CopyToAsync(buffer, request.HttpContext.RequestAborted);

byte[] rawBody = buffer.ToArray();
var signatureValues = request.Headers["ms-signature"];
string? signature = signatureValues.Count == 1
    ? signatureValues[0]
    : null;

bool isValid = WebhookSignature.IsValid(signature, rawBody, secretKey);

Use isValid to decide whether to accept the notification. If valid, reliably save or queue rawBody before acknowledging it; if invalid, do not process it. Implement storage, processing and the HTTP response in your endpoint.

3. Acknowledge and process

Valid notifications

Return HTTP 200 promptly after you have reliably accepted the notification, for example by saving or queueing it. Process it asynchronously if your business logic takes longer.

Invalid notifications

Do not process a notification with an invalid signature or unusable content. Record the rejection without exposing sensitive data, and return HTTP 200 for the rejected content.

Temporary failures: If you cannot reliably accept a valid webhook, return an error such as HTTP 503 rather than acknowledging it. Plusius treats a successful 2xx response as delivered; use 200 for your acknowledgement.

Plusius retries delivery after communication failures or non-2xx responses, with increasing delays and a configured retry limit. A repeated delivery can also occur if the response is lost, so make processing idempotent.

Use a stable event identifier where one is available, or agree an appropriate idempotency key with Plusius. Do not assume notifications arrive in order. Apply event and status changes according to the contract for your integration.

4. Test your signature verification

Use these example values to check that your verification code works. They are for testing the signature calculation only; the example body is not a webhook payload specification.

Example body

{"event":"payment.completed"}

The UTF-8 body must end immediately after }, with no extra spaces or newline.

Example secret

example-secret

This is a made-up secret for the test. Use your Plusius-provided secret for real webhooks.

With that body and secret, the expected ms-signature header is:

v1,F1D2A6C3869EE32F40748151922757614A1FD17B30726492326FBEDF897ABFEF

Your verification method should return true for these values. Change one character in the body and it should return false. Also test a missing or malformed header, an unsupported version and the wrong secret.

Test your integration. Once the signature check works, use the test data and environment agreed with Plusius to verify real deliveries, acknowledgements and retries.

Ready to go live?