> ## Documentation Index > Fetch the complete documentation index at: https://docs.blujay.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a partner webhook subscription > Reseller partner `admin` keys only, without `Blujay-Workspace`. One HTTPS endpoint receives the events you choose for every customer, current and future. Each event's `workspace_id` names the customer (the same ID you send in `Blujay-Workspace`), and its `subscription_id` is this subscription's ID. Every customer's events are signed with this subscription's `signing_secret`, shown only in this response. `customer.created`, `customer.paused` and `customer.closed` are sent about your customers themselves. Customers can't see, change or delete this subscription. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/partner/webhook-subscriptions openapi: 3.1.0 info: title: Blujay API version: 1.0.0 description: >- The Blujay API lets you send and receive iMessage, RCS and SMS messages from your Blujay phone numbers, manage contacts, and receive real-time webhooks. Every response uses the same JSON envelope and carries a `trace_id` you can share with support. Authenticate with your workspace API key. servers: - url: https://api.blujay.io description: Production security: - PublicApiKey: [] tags: - name: Auth description: Check which workspace and credential a request is using. - name: Chats description: >- Direct and group conversations between your Blujay numbers and your contacts. - name: Messages description: Send, read, edit, unsend and react to messages. - name: Phone Numbers description: >- Your Blujay numbers, whether each can send right now, and their live sending limits. - name: Capability description: >- Check whether a phone number can be reached by iMessage, RCS or SMS before you send. - name: Contacts description: Create, find, update, tag, assign and opt out contacts. - name: vCards description: >- Saved contact cards that you can send in a message. Recipients get a native contact card over iMessage, SMS or RCS. - name: Team Members description: People in your workspace you can assign contacts to. - name: Workflows description: Enroll contacts in workflows you start manually. - name: Attachments description: >- Upload files once and reuse them in messages, or download files from messages. - name: Calls description: Download call recordings referenced by call webhooks. - name: Webhooks description: Subscribe to events, inspect delivery attempts and verify signatures. - name: Partners description: >- For Blujay reseller partners. A partner runs many customer workspaces through one integration. Partner keys carry a role (`admin` or `messaging`) and name a customer in the `Blujay-Workspace` header. paths: /v1/partner/webhook-subscriptions: post: tags: - Partners summary: Create a partner webhook subscription description: > Reseller partner `admin` keys only, without `Blujay-Workspace`. One HTTPS endpoint receives the events you choose for every customer, current and future. Each event's `workspace_id` names the customer (the same ID you send in `Blujay-Workspace`), and its `subscription_id` is this subscription's ID. Every customer's events are signed with this subscription's `signing_secret`, shown only in this response. `customer.created`, `customer.paused` and `customer.closed` are sent about your customers themselves. Customers can't see, change or delete this subscription. operationId: createPartnerWebhookSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePartnerWebhookSubscriptionRequest' examples: everyCustomer: summary: Received texts and customer changes for every customer value: url: https://example.com/webhooks/blujay event_types: - message.received - message.failed - customer.created - customer.paused - customer.closed responses: '201': description: The new subscription, including its `signing_secret`. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: >- #/components/schemas/PartnerWebhookSubscriptionWithSecret '400': $ref: '#/components/responses/WebhookSubscriptionRejected' '401': $ref: '#/components/responses/Unauthorized' '403': description: The key has the `messaging` role (`PARTNER_ROLE_FORBIDDEN`). headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': $ref: '#/components/responses/NotFound' security: - PublicApiKey: [] components: schemas: CreatePartnerWebhookSubscriptionRequest: type: object additionalProperties: false required: - url - event_types properties: url: type: string examples: - https://example.com/webhooks/blujay format: uri maxLength: 2048 description: >- Your HTTPS endpoint, up to 2,048 characters. It must resolve to a public address. event_types: type: array description: >- The events to send (1–100). Customer events go to this subscription; every other type is sent for every customer. minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/PartnerWebhookSubscribableEventType' webhook_version: $ref: '#/components/schemas/WebhookPayloadVersion' default: '2026-10-30' status: $ref: '#/components/schemas/PublicWebhookSubscriptionStatus' default: active SuccessEnvelope: type: object description: Wraps every successful response. The result is in `data`. required: - status - trace_id - timestamp properties: status: type: string enum: - success trace_id: $ref: '#/components/schemas/TraceId' timestamp: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time client_request_id: type: string description: >- Your `X-Request-ID` header value, echoed back when you send one. Not included on the send responses (`POST /v1/chats` and `POST /v1/chats/{chat_id}/messages`); keep your own mapping from your request ID to the returned message ID there. PartnerWebhookSubscriptionWithSecret: allOf: - $ref: '#/components/schemas/PartnerWebhookSubscription' - type: object required: - signing_secret properties: signing_secret: type: string examples: - whsec_ZXhhbXBsZS1zZWNyZXQtZG8tbm90LXVzZS0xMjM0NTY3OA== pattern: ^whsec_[A-Za-z0-9+/]+={0,2}$ description: >- Shown only in this response; store it securely. Every customer's events are signed with it. ErrorEnvelope: type: object description: >- Wraps every error response. Branch on `error.code`, and include `trace_id` when you contact support. required: - status - error - trace_id - timestamp properties: status: const: error error: $ref: '#/components/schemas/PublicError' trace_id: $ref: '#/components/schemas/TraceId' timestamp: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time client_request_id: type: string description: Your `X-Request-ID` header value, echoed back when you send one. PartnerWebhookSubscribableEventType: description: Any event a workspace subscription can take, plus the customer events. anyOf: - $ref: '#/components/schemas/WebhookSubscribableEventType' - $ref: '#/components/schemas/PartnerWebhookEventType' WebhookPayloadVersion: type: string enum: - '2026-06-14' - '2026-08-01' - '2026-08-20' - '2026-09-02' - '2026-10-03' - '2026-10-30' description: > The payload version for a subscription's events. - `2026-08-20` reports the service you asked for as `requested_service` and the service actually used as `service`. - `2026-09-02` adds message `parts`. - `2026-10-03` adds iMessage group typing with a `participants` snapshot, `reply_to` on message events, voice memos as `audio` parts (`2026-09-02` reports them as `media` parts), and `saved` on the `contact` in `contact.tag_added` and `contact.assigned`. - `2026-10-30` reports contacts' emoji reactions as `reaction.added` / `reaction.removed` with type `custom` and `emoji`, and stickers with type `sticker` and `sticker`. Earlier versions receive them as `message.received`, as before. Earlier versions keep their original payload shapes and never receive group typing. Each event uses the subscription's version at the time the event was created, so changing the version affects only later events. PublicWebhookSubscriptionStatus: type: string enum: - active - disabled TraceId: type: string examples: - trc_8f2a1c0e4b7d pattern: ^trc_[A-Za-z0-9_-]+$ PartnerWebhookSubscription: type: object additionalProperties: false required: - subscription_id - url - event_types - webhook_version - status - signing_secret_hint - created_at - updated_at description: >- One endpoint that receives every customer's events. Each event's `workspace_id` names the customer. properties: subscription_id: $ref: '#/components/schemas/WebhookSubscriptionId' url: type: string examples: - https://example.com/webhooks/blujay format: uri event_types: type: array items: anyOf: - $ref: '#/components/schemas/WebhookEventType' - $ref: '#/components/schemas/PartnerWebhookEventType' webhook_version: $ref: '#/components/schemas/WebhookPayloadVersion' status: $ref: '#/components/schemas/PublicWebhookSubscriptionStatus' signing_secret_hint: type: string examples: - Y3OA== minLength: 6 maxLength: 6 description: Last six characters of the signing secret. created_at: type: string format: date-time updated_at: type: string format: date-time PublicError: type: object required: - code - message - type - http_status - retryable - doc_url - details properties: code: type: string description: Stable, machine-readable error code. Branch on this value. examples: - RATE_LIMIT_EXCEEDED - QUEUE_UNAVAILABLE - FEATURE_NOT_ENABLED message: type: string description: Human-readable explanation. It can change, so don't parse it. type: type: string description: Broad error category. examples: - validation - auth - idempotency - rate_limit - queue - feature_gate http_status: type: integer description: The HTTP status code of the response. enum: - 400 - 401 - 403 - 404 - 409 - 413 - 415 - 422 - 429 - 500 - 502 - 503 retryable: type: boolean description: Whether sending the same request again later can succeed. doc_url: type: string format: uri description: Link to documentation for this error code. details: type: array description: >- Extra structured context, such as the fields that failed validation or the limit you hit. items: type: object additionalProperties: true retry_after: type: integer minimum: 1 description: >- Seconds to wait before retrying. Also sent as the `Retry-After` header. reset_at: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time description: When the limit you hit resets. WebhookSubscribableEventType: type: string description: > Events you can subscribe to. - Outbound message events (`message.sent`, `message.delivered`, `message.read`, `message.failed`) cover messages sent through Blujay: the app, workflows, scheduled sends, integrations and the API. `message.accepted` is sent only for API sends. Messages sent outside Blujay aren't included. - `message.received` covers new incoming direct and group messages, not older messages Blujay imports later. - `phone_number.status_updated` is sent when one of your numbers is replaced by a new dedicated number (the old number becomes `unavailable` and the new one `active`), and for numbers a reseller partner assigns (`active`), releases (`unavailable`, `reason_code` `number_released`) or that retire after release (`unavailable`, `sender_retired`). - `phone_number.assigned` and `phone_number.released` are sent when a reseller partner assigns a dedicated number to your workspace or releases one into its quiet period. - `call.ended` is sent once when a phone or FaceTime Audio call on one of your numbers is over. An incoming call nobody answered is sent as `missed` as soon as the ringing stops; a voicemail left afterwards arrives in `call.recording_ready`. - `call.recording_ready` is sent once when a call's recording is ready, after its transcript and summary are done or after at most 30 minutes. enum: - message.accepted - message.sent - message.delivered - message.read - message.failed - message.received - reaction.added - reaction.removed - phone_number.status_updated - contact.tag_added - contact.assigned - chat.typing_indicator.started - chat.typing_indicator.stopped - participant.added - participant.removed - chat.group_name_updated - message.edited - message.unsent - call.ended - call.recording_ready - phone_number.assigned - phone_number.released PartnerWebhookEventType: type: string description: > Events about your customers themselves, sent only to partner webhook subscriptions (`/v1/partner/webhook-subscriptions`). `data.customer_id` names the customer; the envelope's `workspace_id` is your own partner workspace. - `customer.created` is sent when you create a customer. - `customer.paused` is sent when Blujay pauses a customer. - `customer.closed` is sent when a customer is closed (status `closing` while its data can still be exported). enum: - customer.created - customer.paused - customer.closed WebhookSubscriptionId: type: string examples: - whsub_abc123 pattern: ^whsub_[A-Za-z0-9_-]+$ WebhookEventType: type: string description: >- Every event type that can appear on a subscription or in a webhook. Some types are recognized only so older subscriptions keep working and may never be sent. You can add only the types in `WebhookSubscribableEventType`. enum: - message.accepted - message.sent - message.delivered - message.read - message.failed - message.received - reaction.added - reaction.removed - participant.added - participant.removed - chat.group_name_updated - phone_number.status_updated - contact.tag_added - contact.assigned - chat.typing_indicator.started - chat.typing_indicator.stopped - message.edited - message.unsent - call.ended - call.recording_ready - phone_number.assigned - phone_number.released headers: XTraceID: description: >- Unique ID for this request. It matches `trace_id` in the body. Include it when you contact Blujay support. schema: $ref: '#/components/schemas/TraceId' responses: WebhookSubscriptionRejected: description: > The subscription wasn't saved: - `UNSUPPORTED_WEBHOOK_EVENT`: an event type isn't recognized. - `FEATURE_NOT_ENABLED`: an event type is recognized but can't be subscribed to. - `WEBHOOK_URL_INVALID`: the URL isn't HTTPS, includes credentials or a fragment, or is too long. - `WEBHOOK_URL_UNSAFE`: the URL points to a private or blocked address. - `WEBHOOK_URL_UNRESOLVABLE`: the URL's host name doesn't resolve. - `VALIDATION_ERROR`: another field is invalid. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unsafeUrl: value: status: error error: code: WEBHOOK_URL_UNSAFE message: Webhook URL must resolve to a public internet address type: validation http_status: 400 retryable: false doc_url: https://docs.blujay.io/errors/webhook-url-unsafe details: [] trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T00:00:00.000Z' unsupported: value: status: error error: code: UNSUPPORTED_WEBHOOK_EVENT message: Unsupported webhook event type order.shipped type: validation http_status: 400 retryable: false doc_url: https://docs.blujay.io/errors/unsupported-webhook-event details: [] trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T00:00:00.000Z' notSubscribable: value: status: error error: code: FEATURE_NOT_ENABLED message: Webhook event type contact.created is not available yet type: validation http_status: 400 retryable: false doc_url: https://docs.blujay.io/errors/feature-not-enabled details: [] trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T00:00:00.000Z' Unauthorized: description: >- The API key is missing or invalid (`UNAUTHORIZED`), revoked (`API_KEY_REVOKED`) or expired (`API_KEY_EXPIRED`). headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' NotFound: description: The resource doesn't exist or isn't in your workspace. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: PublicApiKey: type: http scheme: bearer bearerFormat: blu_... description: > Your workspace API key, sent as `Authorization: Bearer blu_...`. Workspace admins can find it in the Blujay app under **API**. An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server. Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get `429 RATE_LIMIT_EXCEEDED` with `Retry-After`. **Reseller partner keys.** A partner key acts for one of the partner's customers when the request names it in the `Blujay-Workspace` header (the customer's `workspace_` ID). Without the header it reaches only `/v1/partner/*` and `/v1/me`. Each customer gets the limits above for each partner key, and all of a partner's requests together get ten times those limits; a `429` says which in `error.details[0].scope` (`partner_customer` or `partner`). A `messaging` key can read anything for a customer and change chats, messages, contacts, attachments and vCards; everything else needs an `admin` key (`403 PARTNER_ROLE_FORBIDDEN`). Paused or closing customers can be read but not changed (`409 CUSTOMER_PAUSED` or `CUSTOMER_CLOSING`). Any other workspace ID in the header returns `404 NOT_FOUND`; using the header with any other credential returns `400 WORKSPACE_HEADER_NOT_ALLOWED`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.