{"templateId":"../../../@theme/Templates/Wide.tsx","sharedDataIds":{"sidebar":"sidebar-guides/developer/errors/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-header","error-code-heading","section","panel-left","panel-right"]},"type":"markdown"},"seo":{"title":"Webhook errors","siteUrl":"https://docs.wise.com","projectTitle":"Wise Platform","description":"Handle validation, access, scope, and state errors for Wise webhook subscriptions.","keywords":["webhook errors","subscription errors","callback URL","event type"]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-errors","__idx":0},"children":["Webhook errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"class":"sub-header"},"children":["Handle webhook subscription and test notification errors."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These errors apply when you create, retrieve, delete, or test a profile-level or application-level subscription. For event delivery and retry behaviour, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/webhooks/event-handling"},"children":["webhook event handling"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On this page:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-profile-subscription"},"children":["Create a profile subscription"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-an-application-subscription"},"children":["Create an application subscription"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#get-or-delete-a-subscription"},"children":["Get or delete a subscription"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#test-a-subscription"},"children":["Test a subscription"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#shared-access-errors"},"children":["Shared access errors"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#handle-response-formats"},"children":["Handle response formats"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#retry-webhook-operations"},"children":["Retry webhook operations"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/errors#choose-a-recovery-action"},"children":["shared handling guidance"]}," for choosing an action, displaying messages, and retrying safely."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-profile-subscription","__idx":1},"children":["Create a profile subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /profiles/{profileId}/subscriptions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/webhook/webhookprofilesubscriptioncreate"},"children":["create a profile subscription operation"]}," for the current schema."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"invalid","anchor":"profile-create-invalid"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A required subscription field is missing or malformed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Process every item in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," and every string in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arguments"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Map the returned detail to the affected subscription field."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after correcting the request."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"EVENT_TYPE_NOT_PERMITTED","anchor":"profile-create-event-type-not-permitted"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The event type is not available for profile-level subscriptions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose a supported event or use the application-level operation when the event requires that scope."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after changing the event or subscription scope."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"INVALID_CALLBACK_URL","anchor":"profile-create-invalid-callback-url"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback URL fails formatting, accessibility, HTTPS, or security validation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Correct the endpoint and verify it from the public internet."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Remove redirects or access controls that block validation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid secrets in callback URL query parameters."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after the callback endpoint passes these checks."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"INVALID_CALLBACK_URL\",\n  \"message\": \"The provided callback URL is invalid or not secure\",\n  \"arguments\": [\n    \"http://example.com/webhook\"\n  ]\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"SUBSCRIPTION_LIMIT_EXCEEDED","anchor":"profile-create-subscription-limit-exceeded"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The maximum number of subscriptions for the event type has been reached."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List and reconcile existing subscriptions, then reuse or delete one before creating another."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after reducing the number of subscriptions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-an-application-subscription","__idx":2},"children":["Create an application subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /applications/{clientKey}/subscriptions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/webhook/webhookapplicationsubscriptioncreate"},"children":["create an application subscription operation"]}," for the current schema."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"invalid","anchor":"application-create-invalid"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A required application subscription field is missing or malformed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Process every returned error and compare the request with the operation schema."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after correcting the request."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"EVENT_TYPE_NOT_PERMITTED","anchor":"application-create-event-type-not-permitted"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The event type is not available for application-level subscriptions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose a supported event or use the profile-level operation when the event requires that scope."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after changing the event or subscription scope."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"INVALID_CALLBACK_URL","anchor":"application-create-invalid-callback-url"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback URL fails formatting, accessibility, HTTPS, or security validation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Correct and verify the public HTTPS callback endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after the callback URL passes validation."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"SUBSCRIPTION_LIMIT_EXCEEDED","anchor":"application-create-subscription-limit-exceeded"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The application has reached the subscription limit for the selected event type."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List and reconcile existing subscriptions, then reuse or delete one before creating another."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after reducing the number of subscriptions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-or-delete-a-subscription","__idx":3},"children":["Get or delete a subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoints:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /profiles/{profileId}/subscriptions/{subscriptionId}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /profiles/{profileId}/subscriptions/{subscriptionId}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /applications/{clientKey}/subscriptions/{subscriptionId}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /applications/{clientKey}/subscriptions/{subscriptionId}"]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"invalid_request"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request contains an invalid subscription identifier or path parameter."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Compare the parameter with the applicable operation schema and correct it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not retry the unchanged request."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"SUBSCRIPTION_NOT_FOUND"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The subscription is not available for the supplied owner."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the owner and subscription ID together."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show a generic not-found message."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile the appropriate subscription list before removing a cached record."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after correcting the owner or subscription ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"test-a-subscription","__idx":4},"children":["Test a subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /applications/{clientKey}/subscriptions/{subscriptionId}/test-notifications"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/webhook/webhookapplicationsubscriptiontest"},"children":["test an application subscription operation"]}," for the current schema."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"UNSUPPORTED_VERSION"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The selected event schema version is not supported for the test notification."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the available event information and choose a supported schema version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after selecting a supported version."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"shared-access-errors","__idx":5},"children":["Shared access errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," Any webhook subscription operation"]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"unauthorized"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request is not authenticated for webhook subscription management."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Obtain a valid token and verify the subscription owner."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after correcting authentication."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"forbidden"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authenticated identity cannot manage subscriptions for the selected profile or application."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify token permissions, resource ownership, and subscription scope."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not expose ownership details to an unauthorised caller."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after correcting the access context."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-response-formats","__idx":6},"children":["Handle response formats"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Profile and application subscription operations can use different response envelopes. Support both a single error object and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array. Process every validation item and every string in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arguments"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not assume all operations use the same envelope. Do not parse message text or use it for programmatic branching."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retry-webhook-operations","__idx":7},"children":["Retry webhook operations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Correct validation and callback URL errors before retrying."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Change the event or scope for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EVENT_TYPE_NOT_PERMITTED"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile existing subscriptions for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUBSCRIPTION_LIMIT_EXCEEDED"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Correct authentication or ownership before retrying access errors."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retry transient service failures with exponential backoff and jitter."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile the subscription state after an uncertain create or delete result."]}]}]},"headings":[{"value":"Webhook errors","id":"webhook-errors","depth":1},{"value":"Create a profile subscription","id":"create-a-profile-subscription","depth":2},{"value":"Create an application subscription","id":"create-an-application-subscription","depth":2},{"value":"Get or delete a subscription","id":"get-or-delete-a-subscription","depth":2},{"value":"Test a subscription","id":"test-a-subscription","depth":2},{"value":"Shared access errors","id":"shared-access-errors","depth":2},{"value":"Handle response formats","id":"handle-response-formats","depth":2},{"value":"Retry webhook operations","id":"retry-webhook-operations","depth":2}],"frontmatter":{"template":"../../../@theme/Templates/Wide.tsx","seo":{"title":"Webhook errors","description":"Handle validation, access, scope, and state errors for Wise webhook subscriptions.","keywords":["webhook errors","subscription errors","callback URL","event type"]},"markdown":{"toc":{"hide":true}}},"lastModified":"2026-09-22T05:59:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/developer/errors/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}