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.
Review registration
Shellraims webhooks create --name "Pedidos pagos" --url https://webhooks.example.com/raims --events charge.paid --dry-runReplace the illustrative URL with your endpoint and review events. To register it, use the correct profile after removing
--dry-run; keepdata.idand protect the secret outside logs.Inspect health
Shellraims --profile sandbox --output json webhooks health WEBHOOK_IDRead status and available success/failure history. An accepted
testrequest can also remain pending; check the result at the endpoint.Prepare resumption
Shellraims webhooks set-pause WEBHOOK_ID --is-paused=false --dry-runfalseis explicit and is included in the body. The preview does not resume delivery; send the real request only when the endpoint is ready.Plan rotation
Shellraims webhooks rotate-secret WEBHOOK_ID --grace-period-seconds 86400 --dry-runReview 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
| Command | Purpose |
|---|---|
raims webhooks create | Create a webhook endpoint |
raims webhooks delete | Delete a webhook endpoint |
raims webhooks get | Get a webhook endpoint |
raims webhooks health | Get webhook delivery failures |
raims webhooks list | List webhook endpoints |
raims webhooks rotate-secret | Rotate a webhook signing secret |
raims webhooks set-pause | Pause or resume webhook deliveries using a JSON request |
raims webhooks test | Request a test event for a webhook endpoint |
raims webhooks update | Update 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
raims webhooks [flags]Execution options
--help,-hbooldefault: 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
raims webhooks create [flags]OAuth environments: Sandbox, Production. Success responses: 201.
Example 1
raims --profile PROFILE --output json webhooks create --data-file request.json --dry-runExample 2
raims webhooks create --events="charge.paid" --name="Pedidos pagos" --url="https://webhooks.example.com/raims" --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
Create a webhook
{
"id": "whk_1AbXiWSrsCBoaTg47OcMzC",
"name": "Pedidos pagos",
"url": "https://webhooks.example.com/raims",
"events": [
"charge.paid"
],
"is_active": true,
"disabled_reason": null
}Body fields
--eventsstringArrayrequired 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-activeboolsent only when supplied- Defines whether the destination can receive events after creation.
--namestringrequired in the body sent only when supplied- Name to identify the destination.
--urlstringrequired 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-keystringsent only when supplied- Reuse this optional idempotency key when retrying the same request
Execution options
--data-filestringdefault: empty- Read the JSON request body from a UTF-8 file, or '-' for stdin
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for create
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Create a webhook endpoint.
POST /v1/webhooks
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.
Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input.
JSON body fields:
events array<string> required; allowed: "charge.created", "charge.paid", "charge.canceled", "charge.failed", "refund.requested", "refund.completed", "refund.failed"
is_active boolean optional
name string required
url string required
Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields.
JSON body example (save as request.json):
{
"name": "Pedidos pagos",
"url": "https://webhooks.example.com/raims",
"events": [
"charge.paid"
],
"is_active": true
}
Example values are illustrative. Replace resource IDs and review the request before sending it.raims webhooks delete
Delete a webhook endpoint
raims webhooks delete WEBHOOK_ID [flags]OAuth environments: Sandbox, Production. Success responses: 204.
Example
raims --profile PROFILE --output json webhooks delete WEBHOOK_ID --dry-runRequest headers
--idempotency-keystringsent only when supplied- Reuse this optional idempotency key when retrying the same request
Execution options
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for delete
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Delete a webhook endpoint.
DELETE /v1/webhooks/{webhook_id}
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.raims webhooks get
Get a webhook endpoint
raims webhooks get WEBHOOK_ID [flags]OAuth environments: Sandbox, Production. Success responses: 200.
Example
raims --profile PROFILE --output json webhooks get WEBHOOK_ID --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
Retrieve a webhook
{
"id": "whk_1AbXiWSrsCBoaTg47OcMzC",
"name": "Pedidos pagos",
"url": "https://webhooks.example.com/raims",
"events": [
"charge.paid"
],
"is_active": true,
"disabled_reason": null
}Execution options
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for get
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Get a webhook endpoint.
GET /v1/webhooks/{webhook_id}
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.raims webhooks health
Get webhook delivery failures
raims webhooks health WEBHOOK_ID [flags]OAuth environments: Sandbox, Production. Success responses: 200.
Example
raims --profile PROFILE --output json webhooks health WEBHOOK_ID --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
Destination failing for one hour
{
"status": "failing",
"webhook_id": "whk_1AbXiWSrsCBoaTg47OcMzC",
"first_failure_at": 1792281600,
"last_failure_at": 1792285140,
"last_success_at": 1792278000,
"failure_duration_seconds": 3600
}Execution options
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for health
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Get webhook delivery failures.
GET /v1/webhooks/{webhook_id}/health
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.raims webhooks list
List webhook endpoints
raims webhooks list [flags]OAuth environments: Sandbox, Production. Success responses: 200.
Example
raims --profile PROFILE --output json webhooks list --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
List webhooks
{
"list": [
{
"id": "whk_1AbXiWSrsCBoaTg47OcMzC",
"name": "Pedidos pagos",
"url": "https://webhooks.example.com/raims",
"events": [
"charge.paid"
],
"is_active": true,
"disabled_reason": null,
"disabled_at": null,
"previous_secret_expires_at": null,
"created_at": 1792281600,
"updated_at": 1792281600,
"is_paused": false,
"paused_at": null
}
],
"page": {
"page_size": 10,
"has_next": false,
"has_previous": false,
"next_after": null,
"previous_before": null
}
}Query filters
--afterstringsent only when supplied- Read after this opaque cursor (cannot be combined with --before)
--beforestringsent only when supplied- Read before this opaque cursor (cannot be combined with --after)
--page-sizeint64sent only when supplied- Results per page (the API normalizes the requested size)
Execution options
--allbooldefault: false- Read all pages as separate results (JSON Lines with --output json)
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for list
--max-pagesintdefault: 100- Maximum pages to read with --all (1-10000)
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
List webhook endpoints.
GET /v1/webhooks
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.raims webhooks rotate-secret
Rotate a webhook signing secret
raims webhooks rotate-secret WEBHOOK_ID [flags]OAuth environments: Sandbox, Production. Success responses: 200.
Example 1
raims --profile PROFILE --output json webhooks rotate-secret WEBHOOK_ID --data-file request.json --dry-runExample 2
raims webhooks rotate-secret WEBHOOK_ID --grace-period-seconds=86400 --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
Rotate the signing secret
{
"id": "whk_1AbXiWSrsCBoaTg47OcMzC",
"secret_key": "whsec_ExampleOnlyDoNotUseThisValueAsASecret",
"previous_secret_expires_at": 1792368000
}Body fields
--grace-period-secondsintegersent 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-keystringsent only when supplied- Reuse this optional idempotency key when retrying the same request
Execution options
--data-filestringdefault: empty- Read the JSON request body from a UTF-8 file, or '-' for stdin
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for rotate-secret
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Rotate a webhook signing secret.
POST /v1/webhooks/{webhook_id}/rotate_secret
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.
Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input.
JSON body fields:
grace_period_seconds integer optional
Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields.
JSON body example (save as request.json):
{
"grace_period_seconds": 86400
}
Example values are illustrative. Replace resource IDs and review the request before sending it.raims webhooks set-pause
Pause or resume webhook deliveries using a JSON request
raims webhooks set-pause WEBHOOK_ID [flags]OAuth environments: Sandbox, Production. Success responses: 200.
Example 1
raims --profile PROFILE --output json webhooks set-pause WEBHOOK_ID --data-file request.json --dry-runExample 2
raims webhooks set-pause WEBHOOK_ID --is-paused=true --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
Deliveries paused
{
"id": "whk_1AbXiWSrsCBoaTg47OcMzC",
"is_paused": true,
"paused_at": 1791878400
}Body fields
--is-pausedboolrequired 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-keystringsent only when supplied- Reuse this optional idempotency key when retrying the same request
Execution options
--data-filestringdefault: empty- Read the JSON request body from a UTF-8 file, or '-' for stdin
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for set-pause
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Pause or resume webhook deliveries using a JSON request.
PATCH /v1/webhooks/{webhook_id}/pause
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.
Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input.
JSON body fields:
is_paused boolean required
Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields.
JSON body example (save as request.json):
{
"is_paused": true
}
Example values are illustrative. Replace resource IDs and review the request before sending it.raims webhooks test
Request a test event for a webhook endpoint
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
raims --profile PROFILE --output json webhooks test WEBHOOK_ID --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
Send a test event
{
"event_id": "d36ffb51-e0c6-8a8f-904d-e426cc0b76bb",
"delivery_id": "46be4604-31fc-876a-bbb7-69e204ff9c14"
}Request headers
--idempotency-keystringsent only when supplied- Reuse this optional idempotency key when retrying the same request
Execution options
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for test
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Request a test event for a webhook endpoint.
POST /v1/webhooks/{webhook_id}/test
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.
HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion.raims webhooks update
Update a webhook endpoint
raims webhooks update WEBHOOK_ID [flags]OAuth environments: Sandbox, Production. Success responses: 200.
Example 1
raims --profile PROFILE --output json webhooks update WEBHOOK_ID --data-file request.json --dry-runExample 2
raims webhooks update WEBHOOK_ID --events="charge.paid" --events="refund.completed" --dry-runThe excerpt below shows the CLI contents of data. The envelope also reports status_code and the received request_id.
Update a webhook
{
"id": "whk_1AbXiWSrsCBoaTg47OcMzC",
"name": "Pedidos pagos",
"url": "https://webhooks.example.com/raims",
"events": [
"charge.paid"
],
"is_active": true,
"disabled_reason": null
}Body fields
--eventsstringArraysent only when supplied- Complete list of events the destination should receive. It replaces the previous selection. Repeat the option for each item.
--is-activeboolsent only when supplied- Use true to allow deliveries or false to deactivate the destination.
--namestringsent only when supplied- New webhook name.
--urlstringsent only when supplied- New HTTPS URL that receives events, on the default port 443.
Request headers
--idempotency-keystringsent only when supplied- Reuse this optional idempotency key when retrying the same request
Execution options
--data-filestringdefault: empty- Read the JSON request body from a UTF-8 file, or '-' for stdin
--dry-runbooldefault: false- Validate and preview the request without credentials or network access
--help,-hbooldefault: false- help for update
--show-headersbooldefault: false- Show public response headers without credentials or cookies
--timeoutdurationdefault: 1m0s- Total request timeout, including retries (for example 30s or 2m)
See global options.
Update a webhook endpoint.
PATCH /v1/webhooks/{webhook_id}
Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth.
Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header.
OAuth environments accepted by this operation: Sandbox, Production.
Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input.
JSON body fields:
events array<string> optional
is_active boolean optional
name string optional
url string optional
Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields.
JSON body example (save as request.json):
{
"events": [
"charge.paid",
"refund.completed"
]
}
Example values are illustrative. Replace resource IDs and review the request before sending it.