# Create a Webhook Subscriber `POST /v2/webhook-subscribers` Core API v2, Webhook Subscribers. Create a new Webhook Subscriber **Authentication:** Send `Authorization: Bearer `. To authenticate, generate a Secret API Key from your ODUS Dashboard and include it in the `Authorization` header as follows: `Authorization: Bearer ` ## Request body Content type `application/json`, required. Type: object (CreateWebhookSubscriberRequestDTO). - `recipientUrl` (string, required): The URL to send the webhook to. Must be a valid HTTPS URL. Example: `https://my-be-url.com/webhooks`. - `subscribedTo` (array of string, required): Each item: One of `customer.created`, `customer.updated`, `blacklist.added`, `blacklist.removed`, `subscription.active`, `subscription.cancelled`, `subscription.updated`, `payment.created`, `payment.succeeded`, `payment.captured`, `payment.attempt_failed`, `payment.requires_action`, `payment.updated`, `payment.cancelled`, `payment.chargebacked`, `payment.reversed`, `transaction.reverse_failed`, `transaction.capture_failed`, `invoice.created`, `invoice.paid`, `invoice.voided`, `invoice.updated`, `product.created`, `product.updated`, `price.created`, `price.updated`, `price.deleted`. - `payloadVersion` (number): The version of the webhook payload this subscriber receives. It is set when the subscriber is created and cannot be changed afterwards, so a later change to the payload never alters what this subscriber is sent. Omit it to get the current default. One of `1`, `2`. Default `1`. Example: `1`. ## Responses ### `201` OK Type: object (WebhookSubscriberWithSecretDTO). - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the webhook subscriber. - `active` (boolean, required): Whether the webhook subscriber is active and will receive events. Example: `true`. - `recipientUrl` (string, required): The URL where webhook events will be delivered via HTTP POST. Example: `https://my-backend.com/webhooks`. - `subscribedTo` (array of string, required): The list of event types this subscriber receives webhooks for. Covers lifecycle events for customers, subscriptions, payments, transactions, invoices, products, and prices. Each item: One of `customer.created`, `customer.updated`, `blacklist.added`, `blacklist.removed`, `subscription.active`, `subscription.cancelled`, `subscription.updated`, `payment.created`, `payment.succeeded`, `payment.captured`, `payment.attempt_failed`, `payment.requires_action`, `payment.updated`, `payment.cancelled`, `payment.chargebacked`, `payment.reversed`, `transaction.reverse_failed`, `transaction.capture_failed`, `invoice.created`, `invoice.paid`, `invoice.voided`, `invoice.updated`, `product.created`, `product.updated`, `price.created`, `price.updated`, `price.deleted`. - `payloadVersion` (number, required): The version of the webhook payload this subscriber receives. It was set when the subscriber was created and cannot be changed afterwards, so a later change to the payload never alters what this subscriber is sent. One of `1`, `2`. Example: `1`. - `sharedSecret` (string, required): The shared secret used to verify webhook signatures. Only returned once upon creation and cannot be retrieved again. Example: `218f5208d105f754025bb5cfa6b6aefd`. ### `202` The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway. Type: object (ProvisioningInProgress). - `status` (string, required): Signals the merchant environment is still being provisioned. One of `provisioning`. - `merchantAccountId` (string, required): The merchant account whose environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`. ### Errors - `400`: The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; or `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it. - `401`: No API key was supplied, or the key is not valid. `type` is `authentication_error`. - `403`: The API key is valid but lacks the permission this operation requires. `type` is `permission_error`. - `409`: `type` is `conflict_error`. The supplied `X-Idempotency-Key` was already used with a different request body (`code` is `idempotency_conflict`, and retrying will not help), or the resource is being modified by another in-flight request (`code` is `resource_locked`, and retrying with backoff will). - `429`: Too many requests. A limit applies per operation; requests to other operations are unaffected. `type` is `rate_limit_error`. Use the `Retry-After-global` header to know when to retry. - `500`: The request could not be completed because of an unexpected error. `type` is `api_error`. - `503`: The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. `type` is `api_error`. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff. - `504`: The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly. Every error response has the same body: see [Errors](https://docs.odus.com/docs/guides/api-features/errors.md). --- Generated from the Core API v2 OpenAPI document, https://api.odus.com/openapi.v2.json. Interactive page: https://docs.odus.com/docs/api/core/v2/webhook-subscriber-controller-create