Webhooks

List webhook endpoints

GET

https://api.legitgrails.com/v1/integrations

/webhooks

Bearer

Lists registrations belonging to this API key. signing_secret and OAuth2 client_secret are never returned. OAuth2 entries include their auth configuration.

List webhook endpoints › Responses

Registered webhook endpoints.

WebhookEndpoint[]

WebhookEndpoint

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

WebhookOauthMetadata · readOnly

GET/webhooks

curl https://api.legitgrails.com/v1/integrations/webhooks \
  --header 'Authorization: Bearer <token>'

Example Responses

[
  {
    "id": "9f8768c4-b570-4167-8272-6e781f812d66",
    "api_key_id": "391d72e5-040c-4fc1-95d8-7055b967c864",
    "name": "Live order events",
    "url": "https://partner.example.com/webhooks/legitgrails",
    "events": [
      "order-outcome",
      "update-photos"
    ],
    "created_at": "2026-08-17T10:20:30.000Z"
  },
  {
    "id": "d2ceec00-6012-46ad-b669-b982bab9ebbf",
    "api_key_id": "391d72e5-040c-4fc1-95d8-7055b967c864",
    "name": "OAuth order events",
    "url": "https://oauth-partner.example.com/webhooks/legitgrails",
    "events": [
      "order-outcome"
    ],
    "created_at": "2026-08-17T10:25:30.000Z",
    "auth": {
      "type": "oauth2",
      "token_url": "https://oauth-partner.example.com/oauth/token",
      "client_id": "legitgrails-webhooks",
      "scope": null
    }
  }
]

json

application/json

Create a webhook endpoint

POST

https://api.legitgrails.com/v1/integrations

/webhooks

Bearer

Registers a public HTTPS endpoint. It receives events for orders created with the same API key. A key can have at most 10 endpoints, and each destination URL must be unique for that key.

Omit auth to use HMAC signatures, or provide an OAuth2 client-credentials configuration. A HMAC signing_secret is returned only when the endpoint is created.

Create a webhook endpoint › Request Body

CreateWebhookRequest

url

string · uri · maxLength: 2048 · pattern: ^https:// · required

Publicly reachable HTTPS destination for webhook deliveries. Redirect responses are not followed.

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

name

string · maxLength: 100

Optional endpoint label.

WebhookOauthRequest

Create a webhook endpoint › Responses

Webhook registered. HMAC registrations include a one-time signing secret; OAuth2 registrations include safe auth metadata instead.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: id, api_key_id, name +4 more
	type = object · requires: id, api_key_id, name +4 more

Properties for Variant 1:

HmacWebhookCreateResponse

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

signing_secret

string · minLength: 64 · maxLength: 64 · readOnly · pattern: ^[a-f0-9]{64}$ · required

HMAC signing secret shown only once in this creation response.

WebhookOauthMetadata · readOnly

POST/webhooks

curl https://api.legitgrails.com/v1/integrations/webhooks \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Live order events",
  "url": "https://partner.example.com/webhooks/legitgrails",
  "events": [
    "order-outcome",
    "update-photos"
  ]
}'

Example Request Body

{
  "name": "Live order events",
  "url": "https://partner.example.com/webhooks/legitgrails",
  "events": [
    "order-outcome",
    "update-photos"
  ]
}

json

application/json

Example Responses

{
  "id": "9f8768c4-b570-4167-8272-6e781f812d66",
  "api_key_id": "391d72e5-040c-4fc1-95d8-7055b967c864",
  "name": "Live order events",
  "url": "https://partner.example.com/webhooks/legitgrails",
  "events": [
    "order-outcome",
    "update-photos"
  ],
  "created_at": "2026-08-17T10:20:30.000Z",
  "signing_secret": "a3f1c024f15aab047210135a3047f5e0354dbf3884cf47e0b6799a7181c742d8"
}

json

application/json

Delete a webhook endpoint

DELETE

https://api.legitgrails.com/v1/integrations

/webhooks/{id}

Bearer

Deletes a webhook endpoint.

Delete a webhook endpoint › path Parameters

id

string · uuid · required

Webhook endpoint UUID returned at registration.

Delete a webhook endpoint › Responses

Webhook deleted. No response body is sent.

No data returned

Audit

List webhook endpoints

GET

https://api.legitgrails.com/v1/integrations

/webhooks

Bearer

Lists registrations belonging to this API key. signing_secret and OAuth2 client_secret are never returned. OAuth2 entries include their auth configuration.

List webhook endpoints › Responses

Registered webhook endpoints.

WebhookEndpoint[]

WebhookEndpoint

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

WebhookOauthMetadata · readOnly

Create a webhook endpoint

POST

https://api.legitgrails.com/v1/integrations

/webhooks

Bearer

Registers a public HTTPS endpoint. It receives events for orders created with the same API key. A key can have at most 10 endpoints, and each destination URL must be unique for that key.

Omit auth to use HMAC signatures, or provide an OAuth2 client-credentials configuration. A HMAC signing_secret is returned only when the endpoint is created.

Create a webhook endpoint › Request Body

CreateWebhookRequest

url

string · uri · maxLength: 2048 · pattern: ^https:// · required

Publicly reachable HTTPS destination for webhook deliveries. Redirect responses are not followed.

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

name

string · maxLength: 100

Optional endpoint label.

WebhookOauthRequest

Create a webhook endpoint › Responses

Webhook registered. HMAC registrations include a one-time signing secret; OAuth2 registrations include safe auth metadata instead.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: id, api_key_id, name +4 more
	type = object · requires: id, api_key_id, name +4 more

Properties for Variant 1:

HmacWebhookCreateResponse

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

signing_secret

string · minLength: 64 · maxLength: 64 · readOnly · pattern: ^[a-f0-9]{64}$ · required

HMAC signing secret shown only once in this creation response.

WebhookOauthMetadata · readOnly

Delete a webhook endpoint

DELETE

https://api.legitgrails.com/v1/integrations

/webhooks/{id}

Bearer

Deletes a webhook endpoint.

Delete a webhook endpoint › path Parameters

id

string · uuid · required

Webhook endpoint UUID returned at registration.

Delete a webhook endpoint › Responses

Webhook deleted. No response body is sent.

No data returned