Create a merchant webhook endpoint

POST

/webhook_endpoints

const url = 'https://api.timbro.dev/v1/webhook_endpoints';
const options = {
  method: 'POST',
  headers: {
    'idempotency-key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"url":"https://example.com","enabledEvents":["payment.succeeded"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.timbro.dev/v1/webhook_endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "url": "https://example.com", "enabledEvents": [ "payment.succeeded" ] }'

Registers an HTTPS endpoint for signed domain events. The signing secret is returned only in this response.

Authorizations

merchantSecretKey

Parameters

Header Parameters

idempotency-key

required

string

>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Request Body^required

application/json

CreateWebhookEndpointRequest

object

url

required

HTTPS endpoint that receives signed events.

string format: uri

enabledEvents

required

Array

>= 1 items <= 4 items unique items

Responses

201

The endpoint and its signing secret. Store the secret securely.

application/json

WebhookEndpointCreated

The endpoint and its signing secret. Store the secret securely.

object

required

Webhook endpoint identifier.

string

/^webhook_endpoint_[0-9a-hjkmnp-tv-z]{24,}$/

object

required

string

Allowed value: webhook_endpoint

url

required

string format: uri

enabledEvents

required

Array

>= 1 items

isEnabled

required

boolean

createdAt

required

string format: date-time

secret

required

Signing secret. Shown only at creation.

string

>= 1 characters

Example

{
  "object": "webhook_endpoint",
  "enabledEvents": [
    "payment.succeeded"
  ]
}

400

The request could not be understood or is not valid for this merchant account.

application/json

InvalidRequestError

The request could not be understood or is not valid for this merchant account.

object

error

required

object

type

required

string

Allowed value: invalid_request

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: parameter_missing parameter_invalid provider_not_available currency_not_supported amount_below_minimum amount_above_maximum checkout_reference_invalid checkout_reference_expired fiscal_buyer_tax_id_invalid fiscal_line_total_invalid fiscal_lines_required payment_split_invalid

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing"
  }
}

401

The credential is missing, malformed, or no longer valid.

application/json

AuthenticationError

The credential is missing, malformed, or no longer valid.

object

error

required

object

type

required

string

Allowed value: authentication_error

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_missing"
  }
}

403

The credential is valid but not permitted to perform this operation on this resource.

application/json

PermissionError

The credential is valid but not permitted to perform this operation on this resource.

object

error

required

object

type

required

string

Allowed value: permission_error

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: merchant_account_not_owned merchant_account_admin_required operation_not_permitted_for_checkout_token live_mode_not_enabled

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "permission_error",
    "code": "merchant_account_not_owned"
  }
}

404

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

application/json

NotFoundError

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

object

error

required

object

type

required

string

Allowed value: invalid_request

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: endpoint_not_found payment_not_found fiscal_document_not_found merchant_account_not_found merchant_profile_not_found payment_split_not_found payment_part_not_found

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "invalid_request",
    "code": "endpoint_not_found"
  }
}

409

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

application/json

ConflictError

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

object

error

required

object

type

required

string

Allowed value: conflict_error

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: idempotency_key_reused idempotency_request_in_progress idempotency_key_expired payment_method_already_in_progress payment_awaiting_verification decline_not_retryable checkout_window_closed fiscal_preset_locked payment_not_editable fiscal_buyer_required fiscal_correction_not_allowed payment_split_not_allowed payment_split_exists payment_split_locked payment_split_not_capturable payment_split_not_expired payment_split_not_renewable payment_split_complete payment_split_part_required payment_part_not_payable fiscal_artifact_not_ready

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_key_reused"
  }
}

422

The request is well-formed but cannot be carried out for this payment or this merchant account.

application/json

UnprocessableRequestError

The request is well-formed but cannot be carried out for this payment or this merchant account.

object

error

required

object

type

required

string

Allowed value: invalid_request

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: merchant_account_not_ready merchant_profile_incomplete payment_description_required merchant_account_provider_mismatch credential_storage_unavailable provider_not_eligible no_eligible_provider currency_not_supported_by_provider currency_not_supported_for_fiscal_document fiscal_total_mismatch fiscal_line_total_invalid fiscal_line_legal_tip_invalid fiscal_document_kind_not_allowed fiscal_document_kind_unsupported fiscal_government_eligibility_required fiscal_government_eligibility_not_allowed

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "invalid_request",
    "code": "merchant_account_not_ready"
  }
}

429

Too many requests. Retry after the interval in the Retry-After header.

application/json

RateLimitError

Too many requests. Retry after the interval in the Retry-After header.

object

error

required

object

type

required

string

Allowed value: rate_limit_error

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: rate_limit_exceeded

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

application/json

ApiError

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

object

error

required

object

type

required

string

Allowed value: api_error

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: internal_error

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "api_error",
    "code": "internal_error"
  }
}

502

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

application/json

ProviderError

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

object

error

required

object

type

required

string

Allowed value: provider_error

code

required

Stable machine-readable code. Branch on this, never on message.

string

Allowed values: provider_unavailable provider_rejected_request

message

required

Human-readable. Wording may change; not a stable contract.

string

param

Dotted path to the offending request field.

string

docUrl

required

string format: uri

requestId

required

Correlation id, also returned as the Request-Id header.

string

/^request_[0-9a-hjkmnp-tv-z]{24,}$/

Example

{
  "error": {
    "type": "provider_error",
    "code": "provider_unavailable"
  }
}

Create a merchant webhook endpoint

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

502

Example

Request Body^required