Docs
Checking Raims account
Raims CLIAPI commands

raims webhooks

Manage webhook endpoints

From command to result

Register only your integration's authorized endpoint and protect the returned signing secret. Health inspection, test requests, pausing, and rotation are independent actions.

Configure the profile and credential before running real reads. With an API key, the key determines the company and environment. --environment selects an environment only for OAuth.

  1. Review registration

    Shell
    raims webhooks create --name "Pedidos pagos" --url https://webhooks.example.com/raims --events charge.paid --dry-run

    Replace the illustrative URL with your endpoint and review events. To register it, use the correct profile after removing --dry-run; keep data.id and protect the secret outside logs.

  2. Inspect health

    Shell
    raims --profile sandbox --output json webhooks health WEBHOOK_ID

    Read status and available success/failure history. An accepted test request can also remain pending; check the result at the endpoint.

  3. Prepare resumption

    Shell
    raims webhooks set-pause WEBHOOK_ID --is-paused=false --dry-run

    false is explicit and is included in the body. The preview does not resume delivery; send the real request only when the endpoint is ready.

  4. Plan rotation

    Shell
    raims webhooks rotate-secret WEBHOOK_ID --grace-period-seconds 86400 --dry-run

    Review overlap with the previous secret before requesting rotation. After the real request, add the new secret to the verifier and respect previous_secret_expires_at; do not print it in shared logs.

Choose a command

CommandPurpose
raims webhooks createCreate a webhook endpoint
raims webhooks deleteDelete a webhook endpoint
raims webhooks getGet a webhook endpoint
raims webhooks healthGet webhook delivery failures
raims webhooks listList webhook endpoints
raims webhooks rotate-secretRotate a webhook signing secret
raims webhooks set-pausePause or resume webhook deliveries using a JSON request
raims webhooks testRequest a test event for a webhook endpoint
raims webhooks updateUpdate a webhook endpoint

The previews below use --dry-run and do not send the request. Replace placeholders and review the result before sending a write.

Body fields, filters, and headers are sent only when supplied. Execution option defaults do not fill API fields.

raims webhooks

Manage webhook endpoints

Shell
raims webhooks [flags]

Execution options

  • --help, -h bool default: false
    • help for webhooks

See global options.

Subcommands: raims webhooks create, raims webhooks delete, raims webhooks get, raims webhooks health, raims webhooks list, raims webhooks rotate-secret, raims webhooks set-pause, raims webhooks test, raims webhooks update.

raims webhooks create

Create a webhook endpoint

Shell
raims webhooks create [flags]

OAuth environments: Sandbox, Production. Success responses: 201.

Example 1

Shell
raims --profile PROFILE --output json webhooks create --data-file request.json --dry-run

Example 2

Shell
raims webhooks create --events="charge.paid" --name="Pedidos pagos" --url="https://webhooks.example.com/raims" --dry-run

Body fields

  • --events stringArray required in the body sent only when supplied
    • Codes of the events this destination should receive. Query the available event catalog. Repeat the option for each item.
  • --is-active bool sent only when supplied
    • Defines whether the destination can receive events after creation.
  • --name string required in the body sent only when supplied
    • Name to identify the destination.
  • --url string required in the body sent only when supplied
    • HTTPS URL that receives events. Use the default port 443 and a public address outside Raims.

Request headers

  • --idempotency-key string sent only when supplied
    • Reuse this optional idempotency key when retrying the same request

Execution options

  • --data-file string default: empty
    • Read the JSON request body from a UTF-8 file, or '-' for stdin
  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for create
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks delete

Delete a webhook endpoint

Shell
raims webhooks delete WEBHOOK_ID [flags]

OAuth environments: Sandbox, Production. Success responses: 204.

Example

Shell
raims --profile PROFILE --output json webhooks delete WEBHOOK_ID --dry-run

Request headers

  • --idempotency-key string sent only when supplied
    • Reuse this optional idempotency key when retrying the same request

Execution options

  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for delete
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks get

Get a webhook endpoint

Shell
raims webhooks get WEBHOOK_ID [flags]

OAuth environments: Sandbox, Production. Success responses: 200.

Example

Shell
raims --profile PROFILE --output json webhooks get WEBHOOK_ID --dry-run

Execution options

  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for get
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks health

Get webhook delivery failures

Shell
raims webhooks health WEBHOOK_ID [flags]

OAuth environments: Sandbox, Production. Success responses: 200.

Example

Shell
raims --profile PROFILE --output json webhooks health WEBHOOK_ID --dry-run

Execution options

  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for health
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks list

List webhook endpoints

Shell
raims webhooks list [flags]

OAuth environments: Sandbox, Production. Success responses: 200.

Example

Shell
raims --profile PROFILE --output json webhooks list --dry-run

Query filters

  • --after string sent only when supplied
    • Read after this opaque cursor (cannot be combined with --before)
  • --before string sent only when supplied
    • Read before this opaque cursor (cannot be combined with --after)
  • --page-size int64 sent only when supplied
    • Results per page (the API normalizes the requested size)

Execution options

  • --all bool default: false
    • Read all pages as separate results (JSON Lines with --output json)
  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for list
  • --max-pages int default: 100
    • Maximum pages to read with --all (1-10000)
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks rotate-secret

Rotate a webhook signing secret

Shell
raims webhooks rotate-secret WEBHOOK_ID [flags]

OAuth environments: Sandbox, Production. Success responses: 200.

Example 1

Shell
raims --profile PROFILE --output json webhooks rotate-secret WEBHOOK_ID --data-file request.json --dry-run

Example 2

Shell
raims webhooks rotate-secret WEBHOOK_ID --grace-period-seconds=86400 --dry-run

Body fields

  • --grace-period-seconds integer sent only when supplied
    • Period during which the previous secret may continue signing deliveries. Zero generates a new secret and ends the validity of previous secrets, including during an active transition. Requests already authorized or in progress may arrive with the previous signature.

Request headers

  • --idempotency-key string sent only when supplied
    • Reuse this optional idempotency key when retrying the same request

Execution options

  • --data-file string default: empty
    • Read the JSON request body from a UTF-8 file, or '-' for stdin
  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for rotate-secret
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks set-pause

Pause or resume webhook deliveries using a JSON request

Shell
raims webhooks set-pause WEBHOOK_ID [flags]

OAuth environments: Sandbox, Production. Success responses: 200.

Example 1

Shell
raims --profile PROFILE --output json webhooks set-pause WEBHOOK_ID --data-file request.json --dry-run

Example 2

Shell
raims webhooks set-pause WEBHOOK_ID --is-paused=true --dry-run

Body fields

  • --is-paused bool required in the body sent only when supplied
    • Send true to pause deliveries or false to resume them. Repeating the same value preserves the state and pause date.

Request headers

  • --idempotency-key string sent only when supplied
    • Reuse this optional idempotency key when retrying the same request

Execution options

  • --data-file string default: empty
    • Read the JSON request body from a UTF-8 file, or '-' for stdin
  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for set-pause
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks test

Request a test event for a webhook endpoint

Shell
raims webhooks test WEBHOOK_ID [flags]

OAuth environments: Sandbox, Production. Success responses: 202.

HTTP 202 means the request is pending. Query the returned resource before repeating a write; the command does not wait for completion.

Example

Shell
raims --profile PROFILE --output json webhooks test WEBHOOK_ID --dry-run

Request headers

  • --idempotency-key string sent only when supplied
    • Reuse this optional idempotency key when retrying the same request

Execution options

  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for test
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.

raims webhooks update

Update a webhook endpoint

Shell
raims webhooks update WEBHOOK_ID [flags]

OAuth environments: Sandbox, Production. Success responses: 200.

Example 1

Shell
raims --profile PROFILE --output json webhooks update WEBHOOK_ID --data-file request.json --dry-run

Example 2

Shell
raims webhooks update WEBHOOK_ID --events="charge.paid" --events="refund.completed" --dry-run

Body fields

  • --events stringArray sent only when supplied
    • Complete list of events the destination should receive. It replaces the previous selection. Repeat the option for each item.
  • --is-active bool sent only when supplied
    • Use true to allow deliveries or false to deactivate the destination.
  • --name string sent only when supplied
    • New webhook name.
  • --url string sent only when supplied
    • New HTTPS URL that receives events, on the default port 443.

Request headers

  • --idempotency-key string sent only when supplied
    • Reuse this optional idempotency key when retrying the same request

Execution options

  • --data-file string default: empty
    • Read the JSON request body from a UTF-8 file, or '-' for stdin
  • --dry-run bool default: false
    • Validate and preview the request without credentials or network access
  • --help, -h bool default: false
    • help for update
  • --show-headers bool default: false
    • Show public response headers without credentials or cookies
  • --timeout duration default: 1m0s
    • Total request timeout, including retries (for example 30s or 2m)

See global options.