Webhooks

POST /api/webhook_endpoints

curl -X POST 'https://sandbox.partner.miete24.com/api/webhook_endpoints' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://example.com/partnerhub/webhook" }'

const response = await fetch('https://sandbox.partner.miete24.com/api/webhook_endpoints', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com/partnerhub/webhook' }),
});
const endpoint = await response.json();
// Store endpoint.secret now: it is never returned again.

{
  "id": "01K70PZ3QF8W6N2D4R7T9V1X5B",
  "url": "https://example.com/partnerhub/webhook",
  "active": true,
  "secret": "9b1d4c7e2a5f8b0c3d6e9f1a4b7c0d2e5f8a1b4c7d0e3f6a9b2c5d8e1f4a7b0c",
  "createdAt": "2026-10-07T09:00:00+02:00"
}

Errors: 422 when the URL is missing, not https or not publicly reachable; 409 when this URL is already registered or you already have 20 endpoints; 401 for a missing or invalid API key.

All endpoint operations & code samples → Webhook Endpoint reference

Know the events

PartnerHub currently sends one event type. It fires on every status change of a financing case: when its quote, contract or quote request moves to a new status. That includes quotes you created with "submitFinancing": false.

To react to a canceled or rejected order, filter on data.toStatus:

Every other status (for example finance_accepted or completed) arrives the same way; the full list is on the Lifecycle page. One cancellation can produce two events: when a case already has a contract, both the contract and the quote are canceled, and each sends its own event.

Read the payload

Each event is a JSON POST to your URL. This is a cancellation during the review:

{
  "id": "01K70Q8V6M3J5Z2R9T4X7B1C8D",
  "event": "financing_case.status_changed",
  "occurredAt": "2026-10-07T09:15:00+02:00",
  "version": 1,
  "data": {
    "financingCaseId": "019e964c-fb93-73a6-a672-254c170c72d9",
    "fromStatus": "finance_review",
    "toStatus": "canceled",
    "status": "canceled",
    "transition": "cancel",
    "quoteId": "019e964c-fb94-7c1e-9f0a-3b5d8e2a6c41"
  }
}

The payload does not include a reason for a cancellation. New fields may be added to data without a new version; ignore fields you don't know (see Versioning & Deprecation).

Verify the signature

import crypto from 'node:crypto';

/**
 * Verifies the X-Webhook-Signature header of a PartnerHub webhook request.
 *
 * rawBody must be the request body as a Buffer, exactly as received,
 * before any JSON parsing. secret is the signing secret returned once
 * when you registered the endpoint.
 */
export function verifyPartnerHubSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signatureHeader ?? '', 'base64');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

// Usage with Express:
// app.post('/partnerhub/webhook', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verifyPartnerHubSignature(req.body, req.get('X-Webhook-Signature'), secret)) {
//     return res.sendStatus(401);
//   }
//   const event = JSON.parse(req.body);
//   res.sendStatus(204);
// });

<?php

/**
 * Verifies the X-Webhook-Signature header of a PartnerHub webhook request.
 *
 * $rawBody must be the request body exactly as received, before any JSON
 * decoding. $secret is the signing secret returned once when you registered
 * the endpoint.
 */
function verifyPartnerHubSignature(string $rawBody, string $signatureHeader, string $secret): bool
{
    $expected = base64_encode(hash_hmac('sha256', $rawBody, $secret, true));

    return hash_equals($expected, $signatureHeader);
}

// Usage in plain PHP:
// $rawBody = file_get_contents('php://input');
// $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
// if (!verifyPartnerHubSignature($rawBody, $signature, $secret)) {
//     http_response_code(401);
//     exit;
// }

Respond and handle retries

• Answer with any 2xx status within 5 seconds. Do longer work after you have answered.
• A different status, a timeout or a connection error counts as failed. PartnerHub retries up to 3 times: the first retry after 2 seconds, each further wait 2 times longer, at most 30 seconds. After the last retry the event is not sent again.
• Redirects are not followed: a 3xx answer counts as failed, so register the final URL.
• Events can arrive more than once and not always in order: a retried event can arrive after a newer one. Ignore an id you have already processed. Treat data.status of the event with the latest occurredAt as the current state and ignore older events that arrive late; when in doubt, read the case with GET /api/financing_cases/{id}.
• If you missed an event, read the case at any time with GET /api/financing_cases/{id} (see the Financing Case reference).