Handyman Webhooks – Verbraucheranleitung

The Handyman Webhook Integration delivers real-time notifications to your HTTP endpoints. When data changes occur in Handyman (orders, installations, employee appointments, or reports), the system sends an HTTP POST with a JSON payload to your configured endpoint URLs. This guide explains how to receive, parse, and verify webhook deliveries.

Available Webhook Event Types?

How Webhooks Are Delivered?

HTTP Method and Headers

All webhooks are delivered as HTTP POST requests with the following headers:

• Content-Type: application/json

• X-Webhook-Signature: <base64-encoded signature> (present if HMAC verification is configured; see Verifying Sender Identity)

Expected Response

Respond with HTTP 2xx to acknowledge receipt. Any 4xx, 5xx, or network error is a delivery failure.

Retry Behavior

If delivery fails, the system retries up to 3 times with exponential backoff.

Automatic Endpoint Disabling

The system tracks consecutive delivery failures across messages. If an endpoint accumulates 5 consecutive failed deliveries (across separate webhook events, not just retries within one event), it is automatically disabled until manually re-enabled in configuration. A successful delivery resets the counter to zero.

Payload Structure

Order Events

Sent when one or more orders (or related data such as customers, materials, etc.) change.

{
  "EntityType": "Order",
  "Ids": [1234, 5678],
  "Reason": "Material",
  "ChangedBy": "some-user-id"
}

Fields

Possible values for Reason

Installation Events

Sent when one or more installation records change.

{
  "EntityType": "Installation",
  "Ids": [789, 101],
  "ChangedBy": "some-user-id"
}

Fields

Sent when one or more employee appointments change.

{
  "EntityType": "EmployeeAppointment",
  "Ids": [202, 303],
  "ChangedBy": "some-user-id"
}

Fields

Report Events

Sent when a report has been generated and is ready for download.

{
  "EntityType": "Report",
  "ReportId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "OrderIdentifier": {
    "Id": "1234",
    "ExternalId": "EXT-5678"
  },
  "SasUrl": "https://storage.blob.core.windows.net/reports/...",
  "ChangedBy": "some-user-id"
}

Fields

Verifying Sender Identity (HMAC Signature)?

If an HMAC secret is configured, each webhook includes X-Webhook-Signature with a Base64-encoded HMAC-SHA256 of the raw request body. Verify to ensure authenticity and integrity.

How the Signature Is Computed

1. Raw JSON request body is taken as UTF-8 string.

2. Compute HMAC-SHA256 using your shared secret as key.

3. Base64-encode the hash bytes.

4. Send the Base64 string in the X-Webhook-Signature header.

How to Verify (Step by Step)

1. Read the raw request body as a UTF-8 string; do not re-serialize before verifying.

2. Compute HMAC-SHA256 of the raw body with your secret.

3. Base64-encode the hash.

4. Compare to X-Webhook-Signature using a constant-time comparison.

5. If it matches, accept; otherwise, reject.

Code Examples

C#

using System.Security.Cryptography;
using System.Text;
public bool VerifyWebhookSignature(string rawRequestBody, string headerSignature, string secret)
{
    var secretBytes = Encoding.UTF8.GetBytes(secret);
    var payloadBytes = Encoding.UTF8.GetBytes(rawRequestBody);
    using var hmac = new HMACSHA256(secretBytes);
    var hashBytes = hmac.ComputeHash(payloadBytes);
    var computedSignature = Convert.ToBase64String(hashBytes);
    return computedSignature == headerSignature;
}

import hmac
import hashlib
import base64

def verify_webhook_signature(raw_body: bytes, header_signature: str, secret: str) -> bool:
    secret_bytes = secret.encode('utf-8')
    computed_hash = hmac.new(secret_bytes, raw_body, hashlib.sha256).digest()
    computed_signature = base64.b64encode(computed_hash).decode('utf-8')
    return hmac.compare_digest(computed_signature, header_signature)

const crypto = require('crypto');
function verifyWebhookSignature(rawBody, headerSignature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody, 'utf8');
  const computedSignature = hmac.digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(headerSignature)
  );
}

Best Practices for Consumers?

• Filter out your own changes using ChangedBy. Retrieve your identifier via GSG Handyman Onboarding to prevent infinite loops.

• Respond quickly with HTTP 2xx after persisting the event; do heavy processing asynchronously.

• Handle duplicate deliveries; design processing to be idempotent.

• Handle multiple IDs per delivery for Order, Installation, and EmployeeAppointment events.

• Use the Reason field for Order events to scope processing; if Order, re-process the entire order and children.

• Download reports promptly; SasUrl is time-limited.

• Monitor endpoint health; 5 consecutive failures auto-disable the endpoint; ensure reliable 2xx responses.

• Verify signatures in production when an HMAC secret is configured.

Quick Reference