Salta al contenuto principale
Simbioza

API — webhooks and deliveries

← API — contents

A webhook tells another system about an event without repeatedly polling lists. An administrator must enable webhooks and permit destination hosts. webhooks:read or webhooks:manage is required; a non-administrator manages subscriptions created by the same API key, while an administrator with the matching scope may manage all subscriptions.

POST requires name, an allowed HTTPS target_url, an events list (for example ['*']), and optional boolean active. The HMAC signing secret is returned only when created or rotated; store it at the receiving system. Other GET responses do not expose it. PATCH, DELETE, rotate-secret and delivery retry use ETags.

A content mutation adds a queued delivery. GET deliveries shows attempts, status and destination responses. retry reschedules an existing delivery; it does not mean the remote system has received it. A separately scheduled worker performs delivery and must be configured on the server. These REST examples were verified against the queue without sending to an external address.

The API module's technical documentation describes webhook signatures and payloads. The receiver must verify the HMAC-SHA256 signature against the original request bytes and protect against replay. The API key managing a subscription is not the webhook signing secret.

Operations and verified examples

GET /api/v1/webhooks

Purpose: Returns a paginated list of subscriptions available to the current key.

Permission: webhooks:read. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Query parameters: page[after], page[limit].

Body: no additional input fields; follow the example.

curl --globoff --silent --show-error \
  --request GET \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  "$BASE_URL/api/v1/webhooks?page[limit]=1"

Actual response: HTTP 200.

{
  "data": [
    {
      "id": 1,
      "uuid": "c3219935-f00c-4ccd-aa2d-ed155ecc9831",
      "owner_api_key_id": 1,
      "owner_user_id": 1,
      "name": "API observer",
      "target_url": "https://example.com/hooks/simbioza",
      "events": [
        "*"
      ],
      "active": true,
      "created_at": "2026-11-06 23:08:57",
      "updated_at": "2026-11-06 23:08:57"
    }
  ],
  "meta": {
    "request_id": "b621cf9d278e6902b10f96a7c2f6d79e",
    "page": {
      "limit": 1,
      "total": 1,
      "has_more": false,
      "next_cursor": null
    }
  },
  "links": {
    "self": "/api/v1/webhooks?page%5Blimit%5D=1",
    "next": null
  }
}

Errors verified for this operation: 401, 403. See shared rules for status meanings and problem responses.

POST /api/v1/webhooks

Purpose: Creates a subscription and returns its new signing secret only in this response.

Permission: webhooks:manage. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Query parameters: none.

Body / supported fields: active, events, name, target_url. The example below uses verified values; conditions and list-replacement rules are described at the start of the chapter.

curl --globoff --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "name": "API observer",
  "target_url": "https://example.com/hooks/simbioza",
  "events": [
    "*"
  ],
  "active": true
}' \
  "$BASE_URL/api/v1/webhooks"

Actual response: HTTP 201.

{
  "data": {
    "subscription": {
      "id": 1,
      "uuid": "c3219935-f00c-4ccd-aa2d-ed155ecc9831",
      "owner_api_key_id": 1,
      "owner_user_id": 1,
      "name": "API observer",
      "target_url": "https://example.com/hooks/simbioza",
      "events": [
        "*"
      ],
      "active": true,
      "created_at": "2026-11-06 23:08:57",
      "updated_at": "2026-11-06 23:08:57"
    },
    "secret": "[REDACTED]"
  },
  "meta": {
    "request_id": "673b6de22148feaba0dc6b194655cda1"
  },
  "links": {
    "self": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831"
  }
}

Errors verified for this operation: 401, 403. See shared rules for status meanings and problem responses.

DELETE /api/v1/webhooks/{uuid}

Purpose: Permanently removes a subscription with optimistic concurrency protection.

Permission: webhooks:manage. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Path: uuid. Take values from the preceding response. A page ID is its document key; nodeId is numeric, and a UUID is not a slug.

Query parameters: none.

Body: no additional input fields; follow the example.

Before writing: refresh the GET and set ETAG from its ETag header.

curl --globoff --silent --show-error \
  --request DELETE \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  --header "If-Match: $ETAG" \
  "$BASE_URL/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831"

Actual response: HTTP 204. The body is empty.

Errors verified for this operation: 401, 403. See shared rules for status meanings and problem responses.

GET /api/v1/webhooks/{uuid}

Purpose: Returns one permitted subscription without its signing secret.

Permission: webhooks:read. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Path: uuid. Take values from the preceding response. A page ID is its document key; nodeId is numeric, and a UUID is not a slug.

Query parameters: none.

Body: no additional input fields; follow the example.

curl --globoff --silent --show-error \
  --request GET \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  "$BASE_URL/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831"

Actual response: HTTP 200.

{
  "data": {
    "id": 1,
    "uuid": "c3219935-f00c-4ccd-aa2d-ed155ecc9831",
    "owner_api_key_id": 1,
    "owner_user_id": 1,
    "name": "API observer",
    "target_url": "https://example.com/hooks/simbioza",
    "events": [
      "*"
    ],
    "active": true,
    "created_at": "2026-11-06 23:08:57",
    "updated_at": "2026-11-06 23:08:57"
  },
  "meta": {
    "request_id": "ce22c9cc6d5493b57b2b1026ddc69a27"
  },
  "links": {
    "self": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831"
  }
}

Errors verified for this operation: 401, 403, 404. See shared rules for status meanings and problem responses.

PATCH /api/v1/webhooks/{uuid}

Purpose: Updates a subscription only when the client sends the current If-Match.

Permission: webhooks:manage. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Path: uuid. Take values from the preceding response. A page ID is its document key; nodeId is numeric, and a UUID is not a slug.

Query parameters: none.

Body / supported fields: active, events, name, target_url. The example below uses verified values; conditions and list-replacement rules are described at the start of the chapter.

Before writing: refresh the GET and set ETAG from its ETag header.

curl --globoff --silent --show-error \
  --request PATCH \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "If-Match: $ETAG" \
  --data-raw '{
  "name": "API observer updated"
}' \
  "$BASE_URL/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831"

Actual response: HTTP 200.

{
  "data": {
    "id": 1,
    "uuid": "c3219935-f00c-4ccd-aa2d-ed155ecc9831",
    "owner_api_key_id": 1,
    "owner_user_id": 1,
    "name": "API observer updated",
    "target_url": "https://example.com/hooks/simbioza",
    "events": [
      "*"
    ],
    "active": true,
    "created_at": "2026-11-06 23:08:57",
    "updated_at": "2026-11-06 23:08:58"
  },
  "meta": {
    "request_id": "a50a566b4cb87453a1d4835a86d8ab96"
  },
  "links": {
    "self": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831"
  }
}

Errors verified for this operation: 401, 403, 422. See shared rules for status meanings and problem responses.

GET /api/v1/webhooks/{uuid}/deliveries

Purpose: Returns paginated delivery history for one subscription.

Permission: webhooks:read. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Path: uuid. Take values from the preceding response. A page ID is its document key; nodeId is numeric, and a UUID is not a slug.

Query parameters: page[after], page[limit].

Body: no additional input fields; follow the example.

curl --globoff --silent --show-error \
  --request GET \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  "$BASE_URL/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/deliveries?page[limit]=1"

Actual response: HTTP 200.

{
  "data": [
    {
      "id": 7,
      "uuid": "f122cfca-2466-4280-b400-f5c9efa5b5ee",
      "event_id": "a1e4ee61-0e44-4bbe-b070-bb4f45446646",
      "event": "calendar_events.deleted",
      "status": "pending",
      "attempts": 0,
      "available_at": "2026-11-06 23:08:58",
      "delivered_at": null,
      "response_status": null,
      "response_body": null,
      "last_error": null,
      "created_at": "2026-11-06 23:08:58",
      "updated_at": "2026-11-06 23:08:58"
    }
  ],
  "meta": {
    "request_id": "79ac9c3580e735f6146257343e05f331",
    "page": {
      "limit": 1,
      "total": 7,
      "has_more": true,
      "next_cursor": "eyJvZmZzZXQiOjF9"
    }
  },
  "links": {
    "self": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/deliveries?page%5Blimit%5D=1",
    "next": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/deliveries?page%5Blimit%5D=1&page%5Bafter%5D=eyJvZmZzZXQiOjF9"
  }
}

Errors verified for this operation: 401, 403. See shared rules for status meanings and problem responses.

GET /api/v1/webhooks/{uuid}/deliveries/{deliveryUuid}

Purpose: Returns one delivery attempt.

Permission: webhooks:read. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Path: uuid, deliveryUuid. Take values from the preceding response. A page ID is its document key; nodeId is numeric, and a UUID is not a slug.

Query parameters: none.

Body: no additional input fields; follow the example.

curl --globoff --silent --show-error \
  --request GET \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  "$BASE_URL/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/deliveries/f122cfca-2466-4280-b400-f5c9efa5b5ee"

Actual response: HTTP 200.

{
  "data": {
    "id": 7,
    "uuid": "f122cfca-2466-4280-b400-f5c9efa5b5ee",
    "event_id": "a1e4ee61-0e44-4bbe-b070-bb4f45446646",
    "event": "calendar_events.deleted",
    "status": "pending",
    "attempts": 0,
    "available_at": "2026-11-06 23:08:58",
    "delivered_at": null,
    "response_status": null,
    "response_body": null,
    "last_error": null,
    "created_at": "2026-11-06 23:08:58",
    "updated_at": "2026-11-06 23:08:58"
  },
  "meta": {
    "request_id": "a1a068157f70f58e25aaca7e441ee20b"
  },
  "links": {
    "self": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/deliveries/f122cfca-2466-4280-b400-f5c9efa5b5ee"
  }
}

Errors verified for this operation: 401, 403. See shared rules for status meanings and problem responses.

POST /api/v1/webhooks/{uuid}/deliveries/{deliveryUuid}/retry

Purpose: Requeues an existing delivery after checking its ETag.

Permission: webhooks:manage. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Path: uuid, deliveryUuid. Take values from the preceding response. A page ID is its document key; nodeId is numeric, and a UUID is not a slug.

Query parameters: none.

Body: no additional input fields; follow the example.

Before writing: refresh the GET and set ETAG from its ETag header.

curl --globoff --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "If-Match: $ETAG" \
  --data-raw '{}' \
  "$BASE_URL/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/deliveries/f122cfca-2466-4280-b400-f5c9efa5b5ee/retry"

Actual response: HTTP 200.

{
  "data": {
    "id": 7,
    "uuid": "f122cfca-2466-4280-b400-f5c9efa5b5ee",
    "event_id": "a1e4ee61-0e44-4bbe-b070-bb4f45446646",
    "event": "calendar_events.deleted",
    "status": "pending",
    "attempts": 0,
    "available_at": "2026-11-06 23:08:58",
    "delivered_at": null,
    "response_status": null,
    "response_body": null,
    "last_error": null,
    "created_at": "2026-11-06 23:08:58",
    "updated_at": "2026-11-06 23:08:58"
  },
  "meta": {
    "request_id": "186121f98aed702b812e57d49f3b06c8"
  },
  "links": {
    "self": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/deliveries/f122cfca-2466-4280-b400-f5c9efa5b5ee/retry"
  }
}

Errors verified for this operation: 401, 403. See shared rules for status meanings and problem responses.

POST /api/v1/webhooks/{uuid}/rotate-secret

Purpose: Rotates the secret with If-Match and returns the new value only once.

Permission: webhooks:manage. Active API key and permitted destination policy; non-administrators are limited to subscriptions created by this key, while administrators may manage all.

Path: uuid. Take values from the preceding response. A page ID is its document key; nodeId is numeric, and a UUID is not a slug.

Query parameters: none.

Body: no additional input fields; follow the example.

Before writing: refresh the GET and set ETAG from its ETag header.

curl --globoff --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $SIMBIOZA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "If-Match: $ETAG" \
  --data-raw '{}' \
  "$BASE_URL/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/rotate-secret"

Actual response: HTTP 200.

{
  "data": {
    "subscription": {
      "id": 1,
      "uuid": "c3219935-f00c-4ccd-aa2d-ed155ecc9831",
      "owner_api_key_id": 1,
      "owner_user_id": 1,
      "name": "API observer updated",
      "target_url": "https://example.com/hooks/simbioza",
      "events": [
        "*"
      ],
      "active": true,
      "created_at": "2026-11-06 23:08:57",
      "updated_at": "2026-11-06 23:08:58"
    },
    "secret": "[REDACTED]"
  },
  "meta": {
    "request_id": "205b440690d3939f8600c5588c94c0b1"
  },
  "links": {
    "self": "/api/v1/webhooks/c3219935-f00c-4ccd-aa2d-ed155ecc9831/rotate-secret"
  }
}

Errors verified for this operation: 401, 403. See shared rules for status meanings and problem responses.

Receiver — signatures and repeated messages

The server sends a POST with these headers. Verify the signature before JSON decoding; changing whitespace or re-encoding JSON changes the signature.

Content-Type: application/json
X-HeartPhrame-Webhook-Id: <event UUID>
X-HeartPhrame-Webhook-Event: <event name>
X-HeartPhrame-Webhook-Timestamp: <Unix seconds>
X-HeartPhrame-Webhook-Signature: v1=<hex HMAC-SHA256>
<?php
/**
 * EN: Checks a webhook signature over the unmodified raw body.
 * HR: Provjerava potpis webhooka nad neizmijenjenim izvornim tijelom.
 */
function verifySimbiozaWebhook(
    string $rawBody,
    string $timestamp,
    string $signature,
    #[SensitiveParameter] string $secret,
    ?int $now = null,
): bool {
    if (!ctype_digit($timestamp) || abs(($now ?? time()) - (int)$timestamp) > 300) {
        return false;
    }
    $expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $signature);
}

The 300-second tolerance is this example’s policy. Persist processed X-HeartPhrame-Webhook-Id values and do not execute the same business action twice. A valid signature alone does not prevent replay.

Event selectors support an exact name, a namespace with .* (for example pages.*), or *. The webhook body contains event identity and sanitized mutation metadata; it does not send the original request or the full document content.

Server worker

These are administrator CLI commands on your server, separate from REST requests:

vendor/bin/hph api webhooks:status
vendor/bin/hph api webhooks:worker --batch-size=20
vendor/bin/hph api webhooks:worker --watch --sleep=5

--watch runs continuously and should be supervised in production. Avoid unnecessary manual test deliveries. For one failed event, inspect delivery history and use REST retry after fixing the cause.

Attacchi

Nessun attaccamento.

Commenti

0

Non ci sono ancora commenti.

Devi iscriverti per aggiungere un commento.

Creato: Krešimir Mihalj Sep 28, 2026, 6:05 PM · Ultima modifica: Krešimir Mihalj Sep 30, 2026, 11:40 AM