Subscription management

Manage webhook subscriptions in Integrations → Webhooks or through the public API at https://api.remypass.com/api/v1/public/webhook-subscriptions.

Access and permissions

Use an API key belonging to the organisation. Public API access and webhook access must both be enabled. Grant webhooks:read for subscriptions, the catalogue and delivery history, and webhooks:write for creating, updating, deleting, testing and replaying. Grant both permissions to provision and monitor an integration. Existing keys do not automatically gain new permissions; edit their permissions under Integrations.

All lookups and changes are scoped to the key’s organisation. A foreign subscription ID returns 404. The normal public API rate limits apply.

Public API endpoints

Method	Path under /webhook-subscriptions	Permission	Purpose
GET	/	webhooks:read	Paginated subscriptions; filter by active, event, updatedSince
POST	/	webhooks:write	Create an active subscription and return its signing secret once
GET	/events	webhooks:read	Complete event catalogue, grouped actions and synthetic samples
GET	/{id}	webhooks:read	Retrieve a subscription
PUT	/{id}	webhooks:write	Update supplied subscription fields
DELETE	/{id}	webhooks:write	Delete the subscription and its delivery history
GET	/{id}/deliveries	webhooks:read	Paginated history; filter by status, event, eventId, updatedSince
POST	/{id}/test	webhooks:write	Queue a synthetic delivery
POST	/{id}/deliveries/{deliveryId}/replay	webhooks:write	Queue a completed delivery again

See the generated endpoint reference for complete request and response schemas, examples, limits and errors.

Create an integration

Fetch /webhook-subscriptions/events to discover supported events. groups is an object mapping resource names to action names; events contains { "event": "member.created", "sample": { ... } } entries for every supported event. The catalogue is not paginated.

Create a subscription:

curl -X POST 'https://api.remypass.com/api/v1/public/webhook-subscriptions' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "CRM sync",
    "url": "https://example.com/webhooks/remypass",
    "events": ["member.created", "member.updated", "donation.payment_succeeded"],
    "headers": { "X-Integration": "crm" }
  }'

The response is 201 with data.secret. Store this signing secret securely and use it to verify signatures. Reads and updates exclude signing secrets and custom header values. The organisation’s subscription limit is enforced; the default is five endpoints.

The URL must use HTTPS without embedded credentials. Creation checks URL syntax without contacting the receiver. At least one supported event is required. Duplicate event selections are removed. Custom headers support up to 20 string values of at most 2,000 characters each, without line breaks. Host, Content-Type, Content-Length, Connection, Transfer-Encoding and X-RemyPass-* names are reserved.

Send a test:

curl -X POST 'https://api.remypass.com/api/v1/public/webhook-subscriptions/SUBSCRIPTION_ID/test' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "member.created" }'

202 means the delivery is queued. The synthetic payload has test: true and source: "api". An active subscription can test any supported event, including events outside its configured selection. Inspect delivery history for the final outcome.

Update, disable and delete

PUT /webhook-subscriptions/{id} accepts name, description, url, events, headers and active. Only supplied fields change. headers replaces the entire existing map; send {} to clear it. New event selections must remain non-empty.

Set active to false to pause delivery. Queued work checks organisation access and subscription state before sending. An HTTP request already in progress may complete.

Deletion returns 200 with data: null, deletes the endpoint’s delivery history and removes its pending event recipients. This is also the cleanup applied when an organisation is permanently deleted.

Delivery history and replay

List subscriptions and delivery history with page (default 1) and limit (default 10, maximum 100). Lists sort by updatedAt ascending, then _id ascending. updatedSince is an inclusive timestamp with a timezone. History is retained for approximately 90 days and includes payloads, attempt counts, replay counts, response status codes, error messages and delivery timestamps. Internal worker leases are excluded.

Delivery statuses are pending, processing, success, failed and cancelled. Filter by eventId to find the delivery for a payload’s stable id.

curl 'https://api.remypass.com/api/v1/public/webhook-subscriptions/SUBSCRIPTION_ID/deliveries?status=failed&page=1&limit=25' \
  -H 'X-API-Key: YOUR_API_KEY'

Replay with POST /webhook-subscriptions/{id}/deliveries/{deliveryId}/replay. deliveryId is the delivery record’s MongoDB _id, not the webhook payload’s event ID. The subscription must be active. Only success, failed and cancelled deliveries can be replayed; missing, foreign or already queued deliveries return 409. A foreign or inactive subscription returns 404.

Replay keeps the original event ID and payload, resets attempts and increases replayCount. The worker uses the current URL, headers and signing secret. A 200 response means queued; inspect history to confirm delivery. Consumers should deduplicate by payload id.

UI tools and secret rotation

The UI provides the same event selection, samples, tests, history and replay tools. Rotate secret remains a UI operation and shows the new secret once. Update your receiver immediately because queued attempts and replays use the current secret.

The UI’s authenticated management routes remain under /api/v1/webhook-subscriptions; they use user authentication and the integrations management permission. API-key clients use /api/v1/public/webhook-subscriptions.

See delivery and security for signature verification, retry behaviour and delivery guarantees.