Verification

You might want to make sure that your integration is receiving hooks from Pio and not other sources, attackers, etc. When rest hooks is sent to your integration by Pio, the headers will include signature and other information along with the payload so that you can compute and compare/verify the signature on your end. Header will include the following:

Version 1 webhooks

The included headers are:

• X-Pio-Hmac-Sha256: The HMAC-SHA256 signature.
• X-Pio-Delivery-Id : The ID of the webhook, used for idempotency.
• X-Pio-Event-Type: The type of event the webhook refers to. Event types are described in the relevant secetions below.
• X-Pio-Shop-Id: The Pio ID for the shop the webhook is targetting.
• X-Pio-Ext-Shop-Id: The integration provided ID for the shop the webhook is targetting.
• X-Pio-Timestamp: A Unix timestamp indicating the time the request was made.

Example python code for verifying a Pio wehook:

    import hashlib
    import hmac
    import base64
    import secrets

    # your integration's `client_secret`
    client_secret: str = <...>
    # get the payload from the request
    payload: bytes = <...>
    payload_str = payload.decode('utf-8')
    data_to_sign = f"{x_pio_event_type}:{x_pio_delivery_id}:{x_pio_timestamp}:{x_pio_shop_id}:{x_pio_ext_shop_id}:{payload_str}"
    signature = hmac.new(
        client_secret.encode("utf-8"),
        msg=data_to_sign.encode("utf-8"),
        digestmod=hashlib.sha256
    ).digest()
    signature_base64 = base64.b64encode(signature).decode("utf-8")
    # the following should result in `True` if the signatures match
    valid = secrets.compare_digest(signature_base64, x_pio_hmac_sha256)

Version 2 webhooks

In version 2 webhooks, the shop headers have been removed, and other relevant identification details are instead included in the payload.

Currently the version 2 webhook form is only used for the shipment dispatch requests.

The included headers are:

• X-Pio-Hmac-Sha256: The HMAC-SHA256 signature.
• X-Pio-Delivery-Id : The ID of the webhook, used for idempotency.
• X-Pio-Event-Type: The type of event the webhook refers to. Event types are described in the relevant secetions below.
• X-Pio-Timestamp: A Unix timestamp indicating the time the request was made.

Example python code for verifying a Pio wehook:

    import hashlib
    import hmac
    import base64
    import secrets

    # your integration's `client_secret`
    client_secret: str = <...>
    # get the payload from the request
    payload: bytes = <...>
    payload_str = payload.decode('utf-8')
    data_to_sign = f"{x_pio_event_type}:{x_pio_delivery_id}:{x_pio_timestamp}:{payload_str}"
    signature = hmac.new(
        client_secret.encode("utf-8"),
        msg=data_to_sign.encode("utf-8"),
        digestmod=hashlib.sha256
    ).digest()
    signature_base64 = base64.b64encode(signature).decode("utf-8")
    # the following should result in `True` if the signatures match
    valid = secrets.compare_digest(signature_base64, x_pio_hmac_sha256)