Redirect URLs & Result Delivery

The allowed Redirect URL rules, and the parameters delivered on the post-capture redirect.

What is the Redirect URL allow-list?

The Redirect URL a user returns to after capture must be registered on an allow-list. This is a safeguard against sending users to arbitrary addresses (open redirects).

The allow-list is managed in the Console under Integration → Links → Allowed Redirect URLs, and is shared by Link Integration link settings and Server Integration session issuance.

How to register	Description
Add directly in the Console	Add the URL on the Allowed Redirect URLs page
Auto-registration on link create/update	Entering an unregistered URL on a link adds it to the allow-list automatically

Server Integration does not auto-register. POST /v2/hosted-sessions only accepts pre-registered URLs; an unregistered URL returns a 400 error (PETNOWB2B21003).

URL registration rules

Rule	Description
HTTPS required	Only `https://` URLs can be registered. As an exception, loopback development hosts (`localhost`, `127.0.0.1`, `::1`) may use `http://` (any port, path, or query)
Exact match	A link's or session's Redirect URL must match a registered entry character for character (loopback URLs must be registered exactly too, port included)
Reserved parameters forbidden	The query string must not contain the keys `petify_status` or `petify_code` — these are the reserved parameters Petnow appends on the completion redirect
Length limit	URLs are limited to 500 characters

URL deletion rules

A URL cannot be deleted while links use it. Change those links' Redirect URL first.
A URL that was referenced by since-deleted links may keep refusing deletion, for audit-trail preservation. In that case, add the replacement URL and leave the old entry in place — an allow-list entry referenced by no link has no effect on anything.
In-progress capture sessions use the Redirect URL captured at creation time, so editing the allow-list does not affect already-issued sessions.

Completion redirect parameters

When a capture session ends, the user's browser navigates to the Redirect URL, with query parameters appended by Petnow. Your existing query parameters and fragment are preserved — only the result keys are appended — and no other parameters (session IDs, scores, tokens, ...) are ever added.

The redirect happens only for sessions that were actually created. When entry itself is blocked (a duplicate or unregistered externalPetId, an inactive link, and so on), there is no session and your return page is never called.

https://your-service.example.com/petify/return?petify_status=completed&petify_code=hrc_1a2b3c4d5e6f

`petify_status`

Value	Meaning
`completed`	Finished normally
`cancelled`	The user cancelled the capture
`failed`	Processing failed (e.g. insufficient capture quality), or the feature was unavailable
`expired`	The session expired without completing

A Verify mismatch and an Identify no-candidate outcome are completed, not failures — the function result was produced normally, and you learn the match/candidate outcome by reading the result. failed means no result could be produced at all.

`petify_code`

petify_code means different things depending on the status:

`petify_status`	`petify_code`
`completed`	A one-time result/display code (`hrc_...`) — see the issuance matrix below
`failed`	A machine-readable reason. Currently only `FEATURE_UNAVAILABLE` — the feature is unavailable on the account due to its plan/contract state; check your plan in the Console
`cancelled`, `expired`	Never present

When a code is issued on completed:

Session kind	`petify_code`
Link Integration — Register	Absent — `petify_status=completed` itself is the registration outcome; details are in the Console
Link Integration — Verify / Identify	Present — a display-only code (see Link Integration)
Server Integration — every action	Present — a trusted result code (see Server Integration)

Your return page does not need to branch on the session kind — just read whatever parameters you are given. The petify_ prefix exists so the keys cannot collide with query parameters your page already uses, such as status or code.

Return-page implementation tips

No user or session identifier is attached to the redirect, and dynamically appending per-user parameters to the Redirect URL is not supported (exact-match allow-list). With Link Integration, identify the returning user by your own login session in the returning browser; with Server Integration, match the result's sessionId/externalPetId against what you stored at issuance.
Handle the non-completed statuses too (cancelled, failed, expired). For failed or expired sessions, we recommend offering the user a retry path (a fresh link or session).
Result codes stay valid for about 10 minutes after the session completes. The redirect always arrives well within that window, but avoid designs that defer code handling to a batch job.
With Server Integration, design for the redirect possibly being lost — even if the user closes the browser mid-navigation, you can recover the result by polling GET /v2/hosted-sessions/{id}.

Next steps

Link Integration - Issue and manage links in the Console
Server Integration - Issue sessions and receive results via API

Redirect URLs & Result Delivery

On this page