Postman / Insomnia

Subscriby publishes a Postman collection beside the OpenAPI document. It is generated from that document on every deploy, so it can never describe an endpoint the API does not have, and it carries what a plain OpenAPI import leaves out: worked request bodies, one saved response per documented status with the real error codes, a fresh Idempotency-Key on every write, ids that chain from a create to the reads that follow, and a simulated delivery of every webhook event, signed the way Subscriby signs.

Where it livesCopy Anchor Link

PostmanCopy Anchor Link

1. Open Postman → Import → paste https://api.subscriby.net/postman.json, then import https://api.subscriby.net/postman-environment.json the same way.
2. Select the Subscriby REST API environment and paste your sbt_… token into its token variable. The token lives in the environment, never in the collection, so the collection can be shared. Mint one on the dashboard under Settings → API Tokens; see Authentication.
3. Send Projects → List projects. Every request inherits Authorization: Bearer {{token}} from the collection.
4. Create something, say Projects → Create a project. The test script captures the new record's id into projectId, and the requests below it send that id from the same variable, so a folder runs top to bottom without pasting ids. Paste an existing id into a variable to work on a record you already have.
5. Optional query parameters are present and unticked; tick the ones you want.

What each request carriesCopy Anchor Link

• A worked body. Request bodies are filled with values the API accepts, in the shape the field descriptions prescribe: a kind with the one block that kind allows, ids as UUIDs, prices as decimals, times as HH:MM.
• Saved responses. Open the examples dropdown on a request to see one response per documented status: the success shape, and each failure as the error envelope with the code the API answers that status with, its message and its remediation.
• A fresh idempotency key. Every POST, PUT, PATCH and DELETE sends Idempotency-Key: {{$guid}}, a new UUID on each send. Pin the header to a fixed value to replay the original 2xx instead of repeating the write; see Idempotency.
• Tests. Each request asserts that the status is one the reference documents and that a success carries the data envelope, so the collection doubles as a smoke test for the Collection Runner or Newman.
• The contract facts. A request's description ends with the abilities the token needs, the webhook events the call fires and the MCP tools that wrap it, read from the document's x-required-scopes, x-webhook-events and x-mcp-tools.

Testing a webhook receiverCopy Anchor Link

The Webhooks · simulated deliveries folder holds one request per event, grouped by family, each posting the event's documented payload to {{webhookReceiverUrl}} with the SB-Event-Id, SB-Event-Name, Content-Type and User-Agent headers a real delivery carries. A pre-request script computes SB-Signature on each send from {{webhookSecret}}, exactly as the API does (t=<unix seconds>,v1=<HMAC-SHA256 of "<t>.<raw body>">), so your handler sees a delivery it cannot tell from a real one, signature check included.

1. Set webhookReceiverUrl in the environment to your endpoint under development (a tunnel such as ngrok works) and webhookSecret to the secret you verify with.
2. Send Webhooks → Plan → plan.created. Your endpoint should answer 2xx; anything else is what a retry looks like in production.

See Signature verification for the check your handler performs.

InsomniaCopy Anchor Link

Insomnia imports Postman collections as well as OpenAPI documents, so the same two files work there.

1. Open Insomnia → Create → Import → URL → paste https://api.subscriby.net/postman.json; the environment file imports the same way.
2. Set token in the imported environment to your token. Requests inherit the bearer auth.
3. Prefer the raw OpenAPI document? Import https://api.subscriby.net/openapi.json and choose Convert to Design Document to browse operations by tag. In that case add a Before-Request script that sets Idempotency-Key: {% uuid 'v4' %}, since the OpenAPI import carries no scripts.

Syncing updatesCopy Anchor Link

Both files are regenerated on every Subscriby deploy. Re-import to pick up new endpoints: the collection keeps a stable id, so Postman offers to replace the previous copy instead of adding a second one.

Using the spec for codegenCopy Anchor Link

For code generation use the raw OpenAPI document, not the collection, as the input to:

• openapi-generator (open-source, multi-language)
• Speakeasy / Stainless / Fern (commercial, opinionated SDKs)

See the OpenAPI reference for the x-required-scopes extension — any of the codegen tools preserves it as a comment on each operation.