Webhook endpoints

10 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

List webhook endpoints

GET/v1/webhook-endpoints

Webhook endpoints, optionally for one store: URL, description, events and enabled state. The secret is never returned.

Authentication: API key (Bearer)
Permission: webhook:read
Idempotency-Key: Not used
Success: 200

Query parameters

storeIdstring · uuid

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/webhook-endpoints" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

https only; hosts that resolve to private, loopback or link-local addresses are refused (and re-checked on every delivery). The signing secret appears in this response only. Deliveries carry GIEP-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body"> and GIEP-Event-Id.

Authentication: API key (Bearer)
Permission: webhook:manage
Idempotency-Key: Not used
Success: 201

Request body · application/jsonrequired

storeIdstring · uuidrequired
urlstring · urirequired
max 2048 chars
descriptionstring
max 200 chars
eventTypesarray<string>required
min 1 items · max 11 items

Responses

201Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/webhook-endpoints" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "url": "https://shop.example/url",
  "eventTypes": [
    "payment.succeeded"
  ]
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Retrieve a webhook endpoint

GET/v1/webhook-endpoints/{id}

One webhook endpoint (never the secret).

Authentication: API key (Bearer)
Permission: webhook:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/webhook-endpoints/ff1b7c8f-9970-4a23-ad24-3f72-309" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Update a webhook endpoint (URL, events, enabled)

PATCH/v1/webhook-endpoints/{id}

Changes the URL (same https and public-address rules as create), the events, the description or the enabled state. Audited.

Authentication: API key (Bearer)
Permission: webhook:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

urlstring · uri
max 2048 chars
descriptionstringnullable
max 200 chars
eventTypesarray<string>
min 1 items · max 11 items
enabledboolean

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PATCH "$GIEP_API_URL/v1/webhook-endpoints/ff1b7c8f-9970-4a23-ad24-3f72-309" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example/url",
  "description": "string",
  "eventTypes": [
    "payment.succeeded"
  ]
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Delete a webhook endpoint and its delivery log

DELETE/v1/webhook-endpoints/{id}

Deletes an endpoint and its delivery log; the stored secret is overwritten. Audited.

Authentication: API key (Bearer)
Permission: webhook:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X DELETE "$GIEP_API_URL/v1/webhook-endpoints/ff1b7c8f-9970-4a23-ad24-3f72-309" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Delivery log (status, attempts, last HTTP status, next retry)

GET/v1/webhook-endpoints/{id}/deliveries

The latest deliveries to the endpoint: event, status (pending retrying, succeeded, failed), attempts, last HTTP status or error, next retry.

Authentication: API key (Bearer)
Permission: webhook:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/webhook-endpoints/ff1b7c8f-9970-4a23-ad24-3f72-309/deliveries" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Retry a delivery now

POST/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry

Sends a delivery again now (409 when it already succeeded or is being sent).

Authentication: API key (Bearer)
Permission: webhook:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired
deliveryIdstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/webhook-endpoints/ff1b7c8f-9970-4a23-ad24-3f72-309/deliveries/string/retry" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Rotate the signing secret (returned once)

POST/v1/webhook-endpoints/{id}/rotate-secret

Issues a new signing secret, returned in this response only. The old secret stops signing at once (no overlap): update the receiver right away, or accept both secrets while switching. Audited.

Authentication: API key (Bearer)
Permission: webhook:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/webhook-endpoints/ff1b7c8f-9970-4a23-ad24-3f72-309/rotate-secret" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Send a signed `webhook.test` event now

POST/v1/webhook-endpoints/{id}/test

Sends a signed webhook.test event to the endpoint now and records it in the delivery log.

Authentication: API key (Bearer)
Permission: webhook:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/webhook-endpoints/ff1b7c8f-9970-4a23-ad24-3f72-309/test" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Event types an endpoint can subscribe to

GET/v1/webhook-endpoints/event-types

The event types an endpoint can subscribe to.

Authentication: API key (Bearer)
Permission: webhook:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/webhook-endpoints/event-types" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}