Webhooks & Events

Reporting Webhook Configuration

This document provides detailed instructions for configuring the Reporting Webhook within your contract creation, signing, and payment system. This webhook allows real-time updates and notifications based on specified triggers and conditions.

Accessing the Webhook Configuration

To configure the Reporting Webhook, follow these steps:

1. Navigate to Dashboard -> Configurations -> Reporting.

2. Click New Reporting.

3. From the list, choose Webhook and click Next. You will be presented with the webhook configuration page.

Note: Screenshot of webhook configuration interface will be added here.

Webhook Configuration Settings

The webhook configuration page contains several settings that you need to fill out. Below is a detailed description of each setting:

Business Units (Required)

Select the Business Units to which this configuration will be linked. This is a mandatory field.

Triggers (Required)

Select the triggers that will activate the webhook. You can choose multiple triggers from the following options:

Trigger	When it fires
create	Contract (transaction) is created
update	Any field on the contract (transaction) is updated
send	Contract (transaction) email is dispatched to the recipient
review	Recipient reviews the contract through the checkout
expired	Contract reaches its expiry date/time
confirmed	Contract is confirmed/accepted by the recipient
paid	Payment is successfully completed
canceled	Contract is canceled

Payload URL (Required)

Enter the Webhook URL where the payload will be sent. This is a mandatory field.

Content Type (Required)

Select the content type for the payload. This is a mandatory field. The available options are:

• application/json

• application/x-www-form-urlencoded

Secret (Optional)

Enter a secret value that will be used to compute an HMAC-SHA256 hash.

SSL Verification (Required)

Select the SSL verification option. This is a mandatory field and contains the following options:

• Enable SSL verification (default)

• Disable SSL verification

This setting determines if SSL verification is required when making HTTP or HTTPS requests.

Data to Receive (Required)

Select the type of data you want the webhook to receive. This is a mandatory field and contains the following options:

• Only Update Status

• Send me everything (default)

Choose whether to receive only the status update of the contract or all the data of the contract along with the status.

Assignments Fields (Optional)

Provide an array of field names that define which extra field data to report for each company that belongs to the Business Units. This field is optional.

Data Field Mapping (Optional)

Provide an array of field names that define how each field in the transaction (contract) is mapped to the properties in the pushback report. This field is optional.

Example Configuration

Here is an example of how to fill out the configuration:

• Business Units: Provider BU

• Triggers: create, update, send

• Payload URL: https://example.com/webhook

• Content-Type: application/json

• Secret: your_secret_key

• SSL Verification: Enable SSL verification

• Data to Receive: Send me everything

By following these steps and filling out the configuration settings as described, you can successfully set up the Reporting Webhook to meet your specific needs.

For further assistance or troubleshooting, please refer to the support documentation or contact our support team.

Webhook Payload Envelope

Every webhook delivery wraps the contract payload in a standard envelope. The envelope contains the following fields:

Field	Description
eventId	Globally unique identifier for this event (use for idempotency)
eventType	Trigger name that caused this delivery (e.g. contract.confirmed)
apiVersion	API version that produced this payload
timestamp	ISO-8601 UTC timestamp of the first dispatch attempt
data	Full contract payload (or status-only if configured)

contract.confirmed and contract.paid events — when "Send me everything" is selected, the data object includes a checkout field with fully resolved customer, beneficiary, billing, payment, and card data (no raw IDs). See the payload examples below.

Request Headers

Every delivery also includes the following HTTP headers:

Header	Description
X-Webhook-Id	The eventId of the delivery (same as in the envelope body)
X-Webhook-Timestamp	Unix epoch (seconds) — used in signature computation
X-Webhook-Signature	HMAC-SHA256 signature — only present when a Secret is configured

---

HMAC Signature Verification

When you configure a Secret, every delivery includes an X-Webhook-Signature header. Verify it to confirm the request is genuine and has not been tampered with.

How to verify

To verify a delivery, compute an HMAC-SHA256 hash over the string formed by concatenating the timestamp, a dot (.), and the raw request body — using your configured secret as the key. Compare the resulting hex string against the value in the X-Webhook-Signature header.

The X-Webhook-Timestamp header contains the Unix epoch (seconds) used in the signature. Reject any delivery where the timestamp is more than 5 minutes old to prevent replay attacks.

Important: Always use a timing-safe string comparison when checking the signature to prevent timing attacks.

---

Retry Behaviour

If your endpoint does not return a 2xx response, or the connection times out, the delivery is retried automatically using exponential back-off with ±10% random jitter.

Attempt	Delay before retry
1st (immediate)	—
2nd retry	~1 minute
3rd retry	~5 minutes
4th retry	~15 minutes
5th retry	~1 hour
6th retry	~6 hours
7th retry	~24 hours
8th retry	~24 hours

After 8 failed attempts the delivery is marked ERROR and no further automatic retries are made. You can trigger a manual retry from the Dashboard → Contracts → [Contract] → Reporting Events panel.

Delivery Statuses

Status	Meaning
PENDING	Delivery queued, first attempt not yet made
RETRYING	One or more failed attempts; waiting for the next retry
SEND	Endpoint returned 2xx
ERROR	All retry attempts exhausted

---

Idempotency

Each delivery carries a unique eventId. If you receive the same eventId more than once (e.g. after a network failure caused the delivery to be retried even though you already processed it), you should deduplicate on your side using this field.

---

Payload Examples

contract.confirmed — "Send me everything"

Sent when a contract is confirmed. Includes full checkout and payment schedule with resolved data.

{
  "eventId": "evt_5f8d9c0b-9e2b-4b8d-b4e8-9b9d9d2a1f11",
  "eventType": "contract.confirmed",
  "apiVersion": "2025-04-01",
  "timestamp": "2025-04-22T10:33:51Z",
  "data": {
    "id": "C-2025-000123",
    "status": "CONFIRMED",
    "title": "Enterprise Travel Plan",
    "currency": "EUR",
    "externalIds": {
      "sap_id": "12345"
    },
    "items": [...],
    "checkout": {
      "reference": "ABC123",
      "payment": {
        "reference": "stripe-ch-001",
        "provider": "STRIPE"
      },
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]",
        "phone": "[phone]",
        "address": {
          "street": "Main St",
          "house": "1",
          "city": "Berlin",
          "country": "DE",
          "zipCode": "10115"
        }
      },
      "beneficiary": {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[e-mail]"
      },
      "billing": {
        "name": "ACME Corp",
        "address": {
          "street": "Corp Ave",
          "house": "42",
          "city": "Munich",
          "country": "DE",
          "zipCode": "80331"
        },
        "externalIds": {
          "sap_id": "67890"
        },
        "identifiers": {
          "VATIN": "DE123456789"
        }
      },
      "card": {
        "masked": "411111****1111",
        "expiryMonth": "12",
        "expiryYear": "2027",
        "cardHolder": {
          "first": "John",
          "last": "Doe"
        }
      },
      "reporting": {
        "costCenter": "CC-001"
      }
    },
    "paymentSchedule": {
      "type": "ONCE",
      "dueDate": "2025-05-01",
      "paymentTerms": "NET30",
      "events": [
        {
          "id": "pe_001",
          "type": "PAYMENT",
          "paymentDate": "2025-05-01",
          "value": 1500.0,
          "unit": "AMOUNT",
          "status": "PENDING"
        }
      ]
    }
  }
}

contract.paid — "Send me everything"

Sent when payment is successfully completed. Includes the same full checkout structure as contract.confirmed, with the payment event status updated to PAID and the payment reference resolved.

{
  "eventId": "evt_7a1c3d22-b3f4-4c9e-a0d1-1c2b3d4e5f60",
  "eventType": "contract.paid",
  "apiVersion": "2025-04-01",
  "timestamp": "2025-05-01T14:22:09Z",
  "data": {
    "id": "C-2025-000123",
    "status": "PAID",
    "title": "Enterprise Travel Plan",
    "currency": "EUR",
    "externalIds": {
      "sap_id": "12345"
    },
    "items": [...],
    "checkout": {
      "reference": "ABC123",
      "payment": {
        "reference": "stripe-ch-001",
        "provider": "STRIPE"
      },
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]",
        "phone": "[phone]",
        "address": {
          "street": "Main St",
          "house": "1",
          "city": "Berlin",
          "country": "DE",
          "zipCode": "10115"
        }
      },
      "beneficiary": {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[e-mail]"
      },
      "billing": {
        "name": "ACME Corp",
        "address": {
          "street": "Corp Ave",
          "house": "42",
          "city": "Munich",
          "country": "DE",
          "zipCode": "80331"
        },
        "externalIds": {
          "sap_id": "67890"
        },
        "identifiers": {
          "VATIN": "DE123456789"
        }
      },
      "card": {
        "masked": "411111****1111",
        "expiryMonth": "12",
        "expiryYear": "2027",
        "cardHolder": {
          "first": "John",
          "last": "Doe"
        }
      },
      "reporting": {
        "costCenter": "CC-001"
      }
    },
    "paymentSchedule": {
      "type": "ONCE",
      "dueDate": "2025-05-01",
      "paymentTerms": "NET30",
      "events": [
        {
          "id": "pe_001",
          "type": "PAYMENT",
          "paymentDate": "2025-05-01",
          "value": 1500.0,
          "unit": "AMOUNT",
          "status": "PAID"
        }
      ]
    }
  }
}

contract.paid — "Only Update Status"

Sent when payment is completed. Only the envelope fields and contract status are included.

{
  "eventId": "evt_7a1c3d22-b3f4-4c9e-a0d1-1c2b3d4e5f60",
  "eventType": "contract.paid",
  "apiVersion": "2025-04-01",
  "timestamp": "2025-05-01T14:22:09Z",
  "data": {
    "status": "PAID"
  }
}

contract.confirmed — "Only Update Status"

{
  "eventId": "evt_5f8d9c0b-9e2b-4b8d-b4e8-9b9d9d2a1f11",
  "eventType": "contract.confirmed",
  "apiVersion": "2025-04-01",
  "timestamp": "2025-04-22T10:33:51Z",
  "data": {
    "status": "CONFIRMED"
  }
}

---

Signature Verification — Code Examples

Node.js

const crypto = require("crypto");

function verifyWebhookSignature(
  secret,
  timestampHeader,
  body,
  signatureHeader,
) {
  // Reject deliveries older than 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestampHeader)) > 300) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestampHeader}.${body}`)
    .digest("hex");

  const received = signatureHeader.replace(/^sha256=/, "");

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex"),
  );
}

// Express example
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const valid = verifyWebhookSignature(
    process.env.WEBHOOK_SECRET,
    req.headers["X-Webhook-Timestamp"],
    req.body.toString(), // raw bytes as string
    req.headers["X-Webhook-Signature"],
  );
  if (!valid) return res.status(401).send("Invalid signature");
  // process req.body ...
  res.sendStatus(200);
});

Python

import hashlib
import hmac
import time

def verify_webhook_signature(secret: str, timestamp: str, body: str, signature: str) -> bool:
    # Reject deliveries older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{body}".encode(),
        hashlib.sha256
    ).hexdigest()

    received = signature.removeprefix("sha256=")

    # Use constant-time comparison to prevent timing attacks
    return hmac.compare_digest(expected, received)

# Flask example
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    raw_body = request.get_data(as_text=True)
    valid = verify_webhook_signature(
        secret=os.environ['WEBHOOK_SECRET'],
        timestamp=request.headers.get('X-Webhook-Timestamp', ''),
        body=raw_body,
        signature=request.headers.get('X-Webhook-Signature', '')
    )
    if not valid:
        abort(401)
    # process request.json ...
    return '', 200

---

All data is access-controlled and only shows deliveries belonging to your accessible Business Units.