Jump to

• Request
• Response

Test Callback Endpoint

post

/v1/besu/event-subscriptions/test-callback

Use this to verify delivery to an HTTPS callback URL without creating a subscription. It optionally supports OAuth, TLS, and a custom JSON payload.

Request

There are no request parameters for this operation.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Request to test delivery to an event subscription callback endpoint.

Show Source

• callbackUrl(required): string (uri)
  HTTPS callback endpoint to test. HTTP endpoints are rejected by default.
• oauth: object EventSubscriptionOAuthConfig
  OAuth 2.0 configuration for callback authentication.
• payload:
  Optional callback test payload. Accepts any valid JSON value; when omitted, a default test payload is sent.
• tls: object EventSubscriptionTlsConfig
  TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.

{
    "type":"object",
    "description":"Request to test delivery to an event subscription callback endpoint.",
    "required":[
        "callbackUrl"
    ],
    "properties":{
        "callbackUrl":{
            "type":"string",
            "format":"uri",
            "description":"HTTPS callback endpoint to test. HTTP endpoints are rejected by default."
        },
        "oauth":{
            "$ref":"#/components/schemas/EventSubscriptionOAuthConfig",
            "description":"Optional OAuth configuration for callback test authorization."
        },
        "tls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"Optional TLS or mTLS configuration for callback test delivery."
        },
        "payload":{
            "description":"Optional callback test payload. Accepts any valid JSON value; when omitted, a default test payload is sent."
        }
    }
}

Nested Schema : EventSubscriptionOAuthConfig

Type: object

OAuth 2.0 configuration for callback authentication.

Show Source

• authInHeader: boolean
  Default Value: true

  Controls OAuth token request client-auth placement. When true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint. When false, sends client_id and client_secret form fields in the token request body.
• clientId(required): string
  OAuth 2.0 client identifier registered for the callback endpoint.
• clientSecret(required): string
  OAuth 2.0 client secret used for token acquisition.
• grantType: string
  Default Value: client_credentials

  Allowed Values: [ "client_credentials", "refresh_token" ]

  OAuth 2.0 token grant used for callback access-token acquisition. client_credentials obtains an access token with the configured client credentials. refresh_token uses the supplied refreshToken and retains any replacement refresh token returned by the identity provider.
• refreshToken: string
  Required when grantType=refresh_token; pre-provisioned OAuth refresh token used to mint callback access tokens.
• scopes: string
  Space-delimited OAuth scopes requested during token exchange.
• tls: object EventSubscriptionTlsConfig
  TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
• tokenTls: object EventSubscriptionTlsConfig
  TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
• tokenUrl(required): string (uri)
  OAuth 2.0 token endpoint used to obtain access tokens for callbacks.

{
    "type":"object",
    "description":"OAuth 2.0 configuration for callback authentication.",
    "required":[
        "tokenUrl",
        "clientId",
        "clientSecret"
    ],
    "allOf":[
        {
            "if":{
                "required":[
                    "grantType"
                ],
                "properties":{
                    "grantType":{
                        "const":"refresh_token"
                    }
                }
            },
            "then":{
                "required":[
                    "refreshToken"
                ]
            }
        }
    ],
    "properties":{
        "tokenUrl":{
            "type":"string",
            "format":"uri",
            "description":"OAuth 2.0 token endpoint used to obtain access tokens for callbacks."
        },
        "clientId":{
            "type":"string",
            "description":"OAuth 2.0 client identifier registered for the callback endpoint."
        },
        "clientSecret":{
            "type":"string",
            "description":"OAuth 2.0 client secret used for token acquisition."
        },
        "grantType":{
            "type":"string",
            "enum":[
                "client_credentials",
                "refresh_token"
            ],
            "default":"client_credentials",
            "description":"OAuth 2.0 token grant used for callback access-token acquisition.\n<code>client_credentials</code> obtains an access token with the configured client credentials.\n<code>refresh_token</code> uses the supplied <code>refreshToken</code> and retains any replacement refresh token returned by the identity provider.\n"
        },
        "refreshToken":{
            "type":"string",
            "description":"Required when <code>grantType=refresh_token</code>; pre-provisioned OAuth refresh token used to mint callback access tokens."
        },
        "scopes":{
            "type":"string",
            "description":"Space-delimited OAuth scopes requested during token exchange."
        },
        "authInHeader":{
            "type":"boolean",
            "default":true,
            "description":"Controls OAuth token request client-auth placement.\nWhen true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint.\nWhen false, sends <code>client_id</code> and <code>client_secret</code> form fields in the token request body.\n"
        },
        "tokenTls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"Optional TLS or mTLS transport configuration used only for OAuth token-endpoint requests."
        },
        "tls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"OAuth token endpoint TLS configuration. Use <code>tokenTls</code> for new integrations."
        }
    }
}

Match All

OAuth 2.0 configuration for callback authentication.

Show Source

{
    "type":"object",
    "description":"OAuth 2.0 configuration for callback authentication.",
    "required":[
        "tokenUrl",
        "clientId",
        "clientSecret"
    ],
    "allOf":[
        {
            "if":{
                "required":[
                    "grantType"
                ],
                "properties":{
                    "grantType":{
                        "const":"refresh_token"
                    }
                }
            },
            "then":{
                "required":[
                    "refreshToken"
                ]
            }
        }
    ],
    "properties":{
        "tokenUrl":{
            "type":"string",
            "format":"uri",
            "description":"OAuth 2.0 token endpoint used to obtain access tokens for callbacks."
        },
        "clientId":{
            "type":"string",
            "description":"OAuth 2.0 client identifier registered for the callback endpoint."
        },
        "clientSecret":{
            "type":"string",
            "description":"OAuth 2.0 client secret used for token acquisition."
        },
        "grantType":{
            "type":"string",
            "enum":[
                "client_credentials",
                "refresh_token"
            ],
            "default":"client_credentials",
            "description":"OAuth 2.0 token grant used for callback access-token acquisition.\n<code>client_credentials</code> obtains an access token with the configured client credentials.\n<code>refresh_token</code> uses the supplied <code>refreshToken</code> and retains any replacement refresh token returned by the identity provider.\n"
        },
        "refreshToken":{
            "type":"string",
            "description":"Required when <code>grantType=refresh_token</code>; pre-provisioned OAuth refresh token used to mint callback access tokens."
        },
        "scopes":{
            "type":"string",
            "description":"Space-delimited OAuth scopes requested during token exchange."
        },
        "authInHeader":{
            "type":"boolean",
            "default":true,
            "description":"Controls OAuth token request client-auth placement.\nWhen true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint.\nWhen false, sends <code>client_id</code> and <code>client_secret</code> form fields in the token request body.\n"
        },
        "tokenTls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"Optional TLS or mTLS transport configuration used only for OAuth token-endpoint requests."
        },
        "tls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"OAuth token endpoint TLS configuration. Use <code>tokenTls</code> for new integrations."
        }
    }
}

Nested Schema : EventSubscriptionTlsConfig

Type: object

TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.

Show Source

• caCert: string
  PEM-encoded CA certificate used to verify callback server certificates.
• clientCert: string
  PEM-encoded client certificate for callback mTLS.
• clientKey: string
  PEM-encoded PKCS#8 private key for callback mTLS.
• insecureSkipVerify: boolean
  Default Value: false

  When true, skips TLS certificate verification. Use only in controlled non-production environments.

{
    "type":"object",
    "description":"TLS or mTLS configuration for callback delivery. If mTLS is used, both <code>clientCert</code> and <code>clientKey</code> must be provided together.",
    "properties":{
        "caCert":{
            "type":"string",
            "description":"PEM-encoded CA certificate used to verify callback server certificates."
        },
        "clientCert":{
            "type":"string",
            "description":"PEM-encoded client certificate for callback mTLS."
        },
        "clientKey":{
            "type":"string",
            "description":"PEM-encoded PKCS#8 private key for callback mTLS."
        },
        "insecureSkipVerify":{
            "type":"boolean",
            "default":false,
            "description":"When <code>true</code>, skips TLS certificate verification. Use only in controlled non-production environments."
        }
    }
}

Examples

Select an example request_callback_connectivity_check request_callback_connectivity_check_with_oauth

Back to Top

Response

Supported Media Types

• application/json

204 Response

Returns confirmation that callback delivery succeeded.

400 Response

Validation failed.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_400_test_callback_validation_error response_400_test_callback_malformed_json

500 Response

Unexpected service error.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_500_internal_error

503 Response

Event subscriptions are unavailable.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_503_feature_disabled

Back to Top