Webhooks

Webhooks allow your application to receive notifications when events occur on a page belonging to the authenticated user. Webhook endpoints require the authenticated user to own the selected page.

Event types

A webhook can subscribe to one or more of the following events:

Event	Description
new_onetime_payment	A new one-time payment has been paid
new_membership	A membership has been activated
membership_canceled	A membership has been canceled
webhook_deleted	The webhook configuration has been deleted

---

Get webhooks

GET https://api.petje.af/v1/pages/:pageId/webhooks

Returns the webhooks belonging to the selected page.

Scope: webhooks.read

Path Parameters

Name	Type	Description
pageId	string	ID of the page

Query Parameters

Name	Type	Description
limit	integer	Number of webhooks to return. Must be between 1 and 250
after	string	Return results after the webhook with this ID

Headers

Name	Type	Description
Authorization	string	Access token using the Bearer method

Responses

200 — Webhooks successfully retrieved

{
    "count": 2,
    "_embedded": {
        "webhooks": [
            {
                "resource": "webhooks",
                "id": "8bcd47fa-6623-4bd9-98d5-f0b460f2f0f8",
                "url": "https://example.com/webhooks/petjeaf",
                "secret": "generated-webhook-secret",
                "events": [
                    "new_onetime_payment",
                    "new_membership"
                ],
                "_links": {
                    "self": {
                        "href": "https://api.petje.af/v1/pages/5SaEUOWD2b4dN7tJBKMB/webhooks/8bcd47fa-6623-4bd9-98d5-f0b460f2f0f8",
                        "type": "application/hal+json"
                    },
                    "page": {
                        "href": "https://api.petje.af/v1/pages/5SaEUOWD2b4dN7tJBKMB",
                        "type": "application/hal+json"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://api.petje.af/v1/pages/5SaEUOWD2b4dN7tJBKMB/webhooks",
            "type": "application/hal+json"
        },
        "next": null
    }
}

403 — Missing scope or page access

---

Get webhook detail

GET https://api.petje.af/v1/pages/:pageId/webhooks/:id

Returns a single webhook belonging to the selected page.

Scope: webhooks.read

Path Parameters

Name	Type	Description
pageId	string	ID of the page
id	string	ID of the webhook

Headers

Name	Type	Description
Authorization	string	Access token using the Bearer method

Responses

200 — Webhook successfully retrieved

{
    "resource": "webhooks",
    "id": "8bcd47fa-6623-4bd9-98d5-f0b460f2f0f8",
    "url": "https://example.com/webhooks/petjeaf",
    "secret": "generated-webhook-secret",
    "events": [
        "new_onetime_payment",
        "new_membership"
    ],
    "_links": {
        "self": {
            "href": "https://api.petje.af/v1/pages/5SaEUOWD2b4dN7tJBKMB/webhooks/8bcd47fa-6623-4bd9-98d5-f0b460f2f0f8",
            "type": "application/hal+json"
        },
        "page": {
            "href": "https://api.petje.af/v1/pages/5SaEUOWD2b4dN7tJBKMB",
            "type": "application/hal+json"
        }
    }
}

403 — Missing scope or page access

404 — Webhook not found or does not belong to the page

---

Create webhook

POST https://api.petje.af/v1/pages/:pageId/webhooks

Creates a webhook for the selected page. The webhook secret is generated automatically and cannot be supplied by the client.

Scope: webhooks.create or webhooks.write

Path Parameters

Name	Type	Description
pageId	string	ID of the page

Headers

Name	Type	Description
Authorization	string	Access token using the Bearer method
Content-Type	string	application/json

Request Body

Name	Type	Required	Description
url	string	Yes	URL to which webhook requests are sent
events	array	Yes	One or more supported webhook event types

{
    "url": "https://example.com/webhooks/petjeaf",
    "events": [
        "new_onetime_payment",
        "new_membership",
        "membership_canceled",
        "webhook_deleted"
    ]
}

Responses

201 — Webhook successfully created

{
    "resource": "webhooks",
    "id": "8bcd47fa-6623-4bd9-98d5-f0b460f2f0f8",
    "url": "https://example.com/webhooks/petjeaf",
    "secret": "generated-webhook-secret",
    "events": [
        "new_onetime_payment",
        "new_membership",
        "membership_canceled",
        "webhook_deleted"
    ],
    "_links": {
        "self": {
            "href": "https://api.petje.af/v1/pages/5SaEUOWD2b4dN7tJBKMB/webhooks/8bcd47fa-6623-4bd9-98d5-f0b460f2f0f8",
            "type": "application/hal+json"
        },
        "page": {
            "href": "https://api.petje.af/v1/pages/5SaEUOWD2b4dN7tJBKMB",
            "type": "application/hal+json"
        }
    }
}

403 — Missing scope or page access

422 — Validation failed

The following conditions cause a validation error:

• url is missing or is not a valid URL.

• events is missing or empty.

• events contains an unsupported or duplicate event type.

---

Delete webhook

DELETE https://api.petje.af/v1/pages/:pageId/webhooks/:id

Deletes a webhook belonging to the selected page.

If the webhook subscribes to webhook_deleted, a final asynchronous request is sent to the configured URL after deletion.

Scope: webhooks.delete or webhooks.write

Path Parameters

Name	Type	Description
pageId	string	ID of the page
id	string	ID of the webhook

Headers

Name	Type	Description
Authorization	string	Access token using the Bearer method

Responses

204 — Webhook successfully deleted

The response does not contain a body.

403 — Missing scope or page access

404 — Webhook not found or does not belong to the page

---

Receiving webhook requests

Webhook requests are sent as HTTP POST requests containing JSON.

Request headers

Header	Description
Content-Type	application/json
X-Petjeaf-Webhook-Event	The event type
X-Petjeaf-Webhook-Signature	HMAC-SHA256 signature prefixed with sha256=

The signature is created from the raw JSON request body using the webhook secret.

sha256=HMAC_SHA256(raw_request_body, webhook_secret)

Your endpoint should calculate the signature using the raw request body and compare it using a timing-safe comparison.

Failed webhook deliveries are retried up to three times.

One-time payment payload

Event: new_onetime_payment

{
    "event": "new_onetime_payment",
    "data": {
        "amount": 5,
        "currency": "EUR",
        "formatted_amount": "€ 5,00",
        "id": "f4476dbc-19fd-4134-a10f-a5893127db97",
        "page": {
            "id": "5SaEUOWD2b4dN7tJBKMB",
            "name": "Petje.af creator",
            "title": "Support my work"
        },
        "user": {
            "name": "John Doe",
            "id": "ea0fcc69-e615-48d2-a0d7-7c08d49988a1"
        },
        "comment": {
            "id": "ad040078-65d7-45aa-b576-78764970e279",
            "comment": "Keep up the good work!",
            "visibility": "public"
        }
    }
}

The comment, page, or user value can be null when the associated resource is unavailable.

Membership payload

Events:

• new_membership

• membership_canceled

{
    "event": "new_membership",
    "data": {
        "amount": 2,
        "currency": "EUR",
        "interval": "month",
        "amount_formatted": "€ 2,00 per maand",
        "id": "9126eabb-3444-4635-aeba-e10876102e70",
        "page": {
            "id": "5SaEUOWD2b4dN7tJBKMB",
            "name": "Petje.af creator",
            "title": "Support my work"
        },
        "user": {
            "name": "Jane Doe",
            "id": "4098f3fe-50ec-4482-8959-8f623764e1dc"
        },
        "comment": {
            "id": "99d44683-bfa4-40da-8214-c44f0b686fa2",
            "comment": "Happy to join!",
            "visibility": "public"
        }
    }
}

The comment, page, or user value can be null when the associated resource is unavailable.

Webhook deleted payload

Event: webhook_deleted

{
    "event": "webhook_deleted",
    "data": {
        "id": "8bcd47fa-6623-4bd9-98d5-f0b460f2f0f8",
        "page": {
            "id": "5SaEUOWD2b4dN7tJBKMB",
            "name": "Petje.af creator",
            "title": "Support my work"
        }
    }
}