Managing Your Webhook
Registering a webhook URL, reading its status, rotating the signing secret, browsing the delivery history, replaying and sending a test event are dashboard operations, not API calls. They are performed by a signed-in person from your organisation, using the same login they use for the rest of the partner dashboard, on these routes:
| Route | What it does | Body → response |
|---|---|---|
GET /customer/v1/partner-profile/webhooks | Your endpoint: url, status (NotRegistered, Active, Degraded, Disabled), consecutiveFailures, degradedSince, disabledAt, disabledReason. | — |
POST /customer/v1/partner-profile/webhooks | Register your URL. The signing secret is issued by RynoPay and returned once in webhookSecret; a supplied secret is ignored. Calling it again replaces the URL and returns no secret. | { url } → { url, webhookSecret, message } |
PUT /customer/v1/partner-profile/webhooks | Replace the URL. The secret in force is kept (webhookSecret: null). A partner with no webhook yet is registered and gets the secret. | { url } → { webhookSecret, message } |
POST /customer/v1/partner-profile/webhooks/rotate-secret | Issue a new secret. Deliveries carry both signatures until previousSecretExpiresAt (24 hours), so switch whenever you like inside that window. | — → { webhookSecret, previousSecretExpiresAt, message } |
POST /customer/v1/partner-profile/webhooks/enable | Re-enable an endpoint we disabled (see Endpoint health). Re-registering a URL enables it too. | — |
GET /customer/v1/partner-profile/webhooks/deliveries | Delivery history, newest first. Filters: status (Pending, Delivered, Exhausted), eventType, from / to (when the event occurred), page, pageSize (at most 200). | — → { items[], page, pageSize, total }; an item is { id, eventId, eventType, eventVersion, occurredAt, status, attemptCount, nextAttemptAt, lastStatusCode, isReplay, replaySeries, completedAt } |
GET /customer/v1/partner-profile/webhooks/deliveries/{deliveryId} | One delivery: the fields above, every attempt (attemptNo, sentAt, statusCode, responseExcerpt — the first 4 KiB of your response, durationMs, errorKind) and envelopeJson, the exact body we signed and sent (null once purged). | — |
POST /customer/v1/partner-profile/webhooks/deliveries/{deliveryId}/replay | Send that delivery's event again as a new delivery (same event id, Ryno-Replay: true). | — → { deliveryId } of the new delivery |
POST /customer/v1/partner-profile/webhooks/replay | Send every event in a window of at most seven days again, optionally one eventType; includeUnrouted: true also sends events recorded before your endpoint existed. | { from, to, eventType?, includeUnrouted? } → { created } |
POST /customer/v1/partner-profile/webhooks/test | Send a webhook.test event to your URL now, so you can prove your receiver end to end before real events arrive. | — → { eventId } |
GET /customer/v1/partner-profile/webhooks/event-types | The event catalogue: name, version, owner, description. | — |
Responses and errors
Responses use the dashboard envelope { value, isSuccess, error: { code, description } }; the HTTP status follows the error. Codes you can meet:
| Status | Code | Meaning |
|---|---|---|
| 401 | Partner.NotAuthenticated | No partner identity on the login. |
| 409 | Partner.Inactive, Partner.OnboardingNotApproved | Your partner account is not active, or its own onboarding is not approved yet (the event catalogue is readable regardless). |
| 400 | Webhook.UrlNotHttps, Webhook.UrlNotPublic, Webhook.UrlUnresolvable | The URL must be https, resolve, and not point at a private, loopback or link-local address. |
| 400 | Webhook.RangeInvalid, Webhook.RangeTooWide, Webhook.EventExpired | A replay window must end after it starts, span at most seven days, and start within event retention (30 days). |
| 400 | Webhook.EndpointDisabled, Webhook.TestFireRejected | Enable the endpoint first; a test event could not be recorded. |
| 400 | Webhook.StatusUnknown | The delivery history's status filter is not one of Pending, Delivered, Exhausted. |
| 404 | Webhook.EndpointNotFound, Webhook.DeliveryNotFound | No webhook registered yet; no such delivery on your account. |
| 503 | Webhook.DispatcherUnavailable | The webhook service could not be reached. Nothing changed; retry shortly. |
Why this is not on the Partner API
Your API credential is a machine identity scoped to partner.read / partner.write for moving customer data; changing where we send signed events, or re-issuing the key those events are signed with, is an account-administration action and belongs with a person who is accountable for it. A leaked API credential therefore cannot redirect your event stream.
What remains your side of the integration is the wire contract: the signature you verify, and the events you will receive and the payload each one carries.