Skip to main content
POST
Create a webhook endpoint

Authorizations

Authorization
string
header
required

Short-lived JWT issued by the CarHub auth service (Better Auth), verified against its JWKS. Claims: sub (user), org_id (active organisation) and role (owner | admin | member). Used by the dashboard for /mgmt/v1/… only — it is never accepted on /v1/….

Headers

Idempotency-Key
string

Client-generated key (a UUID is ideal) making this POST safe to retry. The first request is executed and its response stored for 24 h; any replay with the same key returns that stored response with Idempotent-Replayed: true and bills nothing. Reusing a key with a different payload is a 409 idempotency_key_reuse.

Required string length: 8 - 255

Body

application/json
url
string<uri>
required

HTTPS only, and must resolve to a public address — private ranges and link-local addresses are refused. Must answer 2xx within 10 seconds.

events
enum<string>[]
required
Minimum array length: 1

An event your endpoint can subscribe to.

Available options:
job.succeeded,
job.failed,
inspection.stage_completed
description
string
Maximum string length: 255
livemode
boolean
default:true

Response

Endpoint created. Store secret now.

id
string
required
Example:

"whe_5DfG8hJk"

object
string
required
Allowed value: "webhook_endpoint"
url
string<uri>
required
Example:

"https://api.garage-dupont.fr/hooks/carhub"

description
string | null
required
events
enum<string>[]
required

Event types this endpoint is subscribed to.

Minimum array length: 1

An event your endpoint can subscribe to.

Available options:
job.succeeded,
job.failed,
inspection.stage_completed
status
enum<string>
required

Automatically moved to disabled after 24 h of consecutive delivery failures; re-enable it from the dashboard.

Available options:
enabled,
disabled
livemode
boolean
required

An endpoint receives events of its own mode only.

created
integer<int64>
required

Epoch seconds, UTC.

Example:

1755300000

consecutive_failures
integer
required

Deliveries that have failed in a row. Reset to 0 by the next success.

Required range: x >= 0
last_success_at
integer<int64> | null
required

Epoch seconds, UTC.

Example:

1755300000

last_error
string | null
required

Transport error or status of the most recent failure.

Example:

"502 Bad Gateway"

secret
string
required

HMAC signing secret, shown once. Every delivery to this endpoint is signed with it in Carhub-Signature.

Example:

"whsec_9Kd8xQmPvL4TnW2sYbRc"