Check an endpoint before relying on it
An endpoint test sends a synthetic signed request through the same transport used for event delivery. It tells an administrator whether the endpoint accepted it, refused it, could not be reached or was never sent.
That distinction helps locate the next action: fix the receiver, the address or the application’s signing configuration.
Example — Find a wrong endpoint path
An administrator tests a new endpoint and receives a rejection response. The request reached a server, so the next step is to inspect its path or verification response rather than treating it as a connection outage.
For engineers
The webhookConfig.testEndpoint operation accepts an endpointId in its request body, uses the stored endpoint and the application’s signing key. It is an update-like operation because it sends real traffic, even though it creates no delivery-log row. It shares sendSignedWebhookRequest with the delivery worker, so timeout, signature header, URL guard and redirect behavior are exercised on the same path.
This is a real outbound request with synthetic claims. The receiver should identify the probe and verify it without treating it as an ordinary business event. It does not create a delivery-log row; the operation records an audit event separately.
The request and response below come from webhook-config.shared.resources-config.schemas.ts, with documentation comments omitted. Send the stored endpoint’s ID in the operation body; the returned URL confirms which destination was tested. The diagnostic includes both the transport verdict and details for correlating the attempt with the receiver.
export const WebhookConfig_TestEndpointRequestDto = z.object({
endpointId: z.string().min(1),
});
export const WebhookConfig_TestEndpointResponseDto = z.object({
endpointId: z.string(),
url: z.string(),
transportIsPlaintext: z.boolean(),
outcome: z.enum(WebhookEndpointProbeOutcome),
responseStatus: z.number().int().optional(),
responseBodyTruncated: z.string().optional(),
failureReason: z.string().optional(),
durationMs: z.number().int().nonnegative(),
signatureJti: z.string(),
attemptedAt: z.date(),
});
Read the diagnostic outcome, not only the API status: a successfully executed probe may return HTTP 200 with UNREACHABLE. Unknown endpoint IDs, missing configuration and rate-limit refusal are request errors.
ACCEPTED means the endpoint returned 2xx. It only supports confidence in signature verification when that receiver actually verifies before responding; a server returning 200 unconditionally proves reachability, not verification. REJECTED retains a response status; UNREACHABLE covers transport failures; NOT_SENT separates a local signing problem.
Acknowledge a verified probe without running business work
Use the receiver verification shown in signed webhook delivery. It verifies the signature and raw-body hash before returning the authenticated synthetic claim. This illustrative handler fragment uses that verifyDelivery helper; acknowledge sends the HTTP response and handleBusinessEventOnce is the receiver’s own durable deduplication and business handler.
const delivery = verifyDelivery(headers, rawBody, applicationPublicKeyPem);
if (delivery.synthetic) {
acknowledge(204);
return;
}
await handleBusinessEventOnce(delivery.deliveryId, delivery.event);
acknowledge(204);
Do not branch on an unverified body field or decoded JWT. A failed verification must not receive a successful acknowledgment. The genuine event path must persist its delivery identity with its business effect; the probe path deliberately performs neither business work nor ordinary delivery processing.
Make the result actionable
Register and expose the webhook configuration’s normal administration operations. The test is rate-limited, and its limiter fails closed if unavailable. Do not add a second generic HTTP test button: it could pass while the actual signing or delivery path fails.
The probe is a diagnostic, not a guarantee of future delivery. After acceptance, emit a real configured resource event and inspect the delivery log and receiver behavior. Keep endpoint test handlers free of unintended business side effects and use HTTPS endpoints just as for production deliveries.