Monitor a TLS order and cancel it on failure

This recipe extends the actual certificate order with a controlled monitoring and cancellation path. It is especially useful when orders are triggered automatically and stuck requests should not be followed up manually.

Prerequisites

• an API key with access to the TLS endpoints
• a valid CSR
• defined rules for when an order is considered stuck or no longer valid from a business perspective
• a job or worker that can repeat status checks

Step 1: Create the certificate order

The order response gives you the id that drives the rest of the workflow.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token"
}
'

If this order should be treated as an explicit renewal, add renewal_of_certificate_id. Monitoring, timeout handling, and cancellation stay the same because a renewal is still created as its own order on the same endpoint.

Store at least the following values from the response:

• id
• status
• order_state
• any validation information returned

Step 2: Poll the order status

Then keep polling the order until it has been issued, clearly failed, or exceeded your acceptable business timeout.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ' \
  --header 'x-api-key: YOUR_API_KEY'

Typical cancellation rules include:

• the order remains in pending for too long
• the required validation was not completed within the expected time window
• a downstream process decides that the order is no longer needed

With the current API, also read:

• order_cancellable
• order_cancellation_mode
• order_cancellable_until

Step 3: Detect timeout or failure

As soon as your monitoring logic decides that the order should no longer continue, mark it internally for cancellation. A common setup combines time limits, status evaluation, and workflow context.

One simple internal decision model could look like this:

{
  "certificate_id": "7K9QW3M2ZT8HJ",
  "maxPendingMinutes": 30,
  "cancelWhenStatusStill": "pending",
  "reason": "dcv-timeout"
}

Step 4: Cancel the order

When the failure or timeout condition has been met, the workflow actively cancels the order so no stale request remains open.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ/cancel' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "note": "Cancelled automatically after DCV timeout in provisioning workflow"
}
'

Use this path when the order is still pending. If the fetched certificate shows order_cancellation_mode for a full DigiCert order cancellation or revocation, use /tls/certificate/{certificate_id}/order-cancel instead.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ/order-cancel' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "comment": "Order revoked automatically after policy timeout"
}
'

Step 5: Confirm the cancellation path

After sending the cancel request, fetch the order one more time so your internal state and the provider-facing state stay aligned.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ' \
  --header 'x-api-key: YOUR_API_KEY'

Practical notes for production workflows

• separate ordering, polling, and cancellation into distinct state transitions
• always store the cancellation reason
• prevent endless loops by defining a hard maximum age for open orders
• alert only on exceptions, not on every pending status
• keep the workflow idempotent so a cancel job can safely run more than once

Result

This turns plain certificate ordering into a controlled lifecycle with a clean timeout and failure path. The same applies to explicit renewal orders created through renewal_of_certificate_id.