Webhooks

Webhooks let you receive real-time HTTP notifications when events happen in your project. When an event fires (e.g. a product is created or an order is paid), Hydra sends a POST request to your configured URL with the event payload. All webhook management endpoints require a secret key.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/webhooks	Secret	List webhook subscriptions
POST	/v1/webhooks	Secret	Create a subscription
GET	/v1/webhooks/{id}	Secret	Get a subscription
PATCH	/v1/webhooks/{id}	Secret	Update a subscription
DELETE	/v1/webhooks/{id}	Secret	Delete a subscription

---

List webhook subscriptions

GET /v1/webhooks

Returns a paginated list of all webhook subscriptions for the project.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1-100)
cursor	string	-	Pagination cursor from a previous response
sort	string	created_at	Sort field: created_at
order	string	desc	Sort direction: asc, desc
fields	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "wh_abc123",
			"url": "https://example.com/webhooks/hydra",
			"events": ["order.created", "order.paid"],
			"status": "active",
			"created_at": "2026-08-10T14:00:00Z",
			"updated_at": "2026-08-10T14:00:00Z"
		},
		{
			"id": "wh_def456",
			"url": "https://example.com/webhooks/inventory",
			"events": ["inventory.low"],
			"status": "active",
			"created_at": "2026-08-05T09:00:00Z",
			"updated_at": "2026-08-05T09:00:00Z"
		}
	],
	"pagination": {
		"cursor": null,
		"has_more": false,
		"total": 2
	}
}

---

Create a subscription

POST /v1/webhooks

Creates a new webhook subscription. The signing secret is returned only once in the creation response – store it securely.

Request body

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint URL (max 2048 chars)
events	string[]	Yes	Array of event types to subscribe to (1-11 events)
status	string	No	active (default) or paused

Request

curl -X POST https://api.hydrajs.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/hydra",
    "events": ["order.created", "order.paid", "product.updated"]
  }'

Response 201

{
	"data": {
		"id": "wh_abc123",
		"url": "https://example.com/webhooks/hydra",
		"events": ["order.created", "order.paid", "product.updated"],
		"status": "active",
		"secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
		"created_at": "2026-08-17T10:00:00Z",
		"updated_at": "2026-08-17T10:00:00Z"
	}
}

---

Get a subscription

GET /v1/webhooks/{id}

Returns a single webhook subscription by ID.

Query parameters

Parameter	Type	Description
fields	string	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "wh_abc123",
		"url": "https://example.com/webhooks/hydra",
		"events": ["order.created", "order.paid", "product.updated"],
		"status": "active",
		"created_at": "2026-08-17T10:00:00Z",
		"updated_at": "2026-08-17T10:00:00Z"
	}
}

---

Update a subscription

PATCH /v1/webhooks/{id}

Updates a webhook subscription. All fields are optional. Send only the fields you want to change.

Request body

Field	Type	Description
url	string	HTTPS endpoint URL (max 2048 chars)
events	string[]	Array of event types (1-11 events). Replaces the entire array
status	string	active or paused

Request

curl -X PATCH https://api.hydrajs.dev/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["order.created", "order.paid", "order.fulfilled", "product.updated"],
    "status": "active"
  }'

Response 200

{
	"data": {
		"id": "wh_abc123",
		"url": "https://example.com/webhooks/hydra",
		"events": ["order.created", "order.paid", "order.fulfilled", "product.updated"],
		"status": "active",
		"created_at": "2026-08-17T10:00:00Z",
		"updated_at": "2026-08-17T10:30:00Z"
	}
}

---

Delete a subscription

DELETE /v1/webhooks/{id}

Permanently deletes a webhook subscription. Pending deliveries for this webhook will not be retried.

Request

curl -X DELETE https://api.hydrajs.dev/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

Event types

Subscribe to any combination of these event types:

Event	Trigger
product.created	A product is created or duplicated
product.updated	A product’s fields are updated
product.deleted	A product is soft-deleted
order.created	A new order is created from checkout
order.paid	Payment is confirmed for an order
order.fulfilled	An order is marked as fulfilled
order.cancelled	An order is cancelled
order.refunded	An order is refunded
customer.created	A new customer is created
customer.updated	A customer’s details are updated
inventory.low	A variant’s stock drops below its low-stock threshold
shipping.zone.created	A shipping zone is created
shipping.zone.updated	A shipping zone is updated
shipping.zone.deleted	A shipping zone is deleted
usage.warning	Monthly API usage approaches the plan limit

---

Webhook payload

Every webhook delivery sends a POST request with the following JSON body:

{
	"id": "evt_abc123",
	"type": "order.paid",
	"created_at": "2026-08-17T10:05:00Z",
	"data": {
		"id": "ord_xyz789",
		"status": "paid",
		"total": 12998,
		"currency": "USD"
	}
}

The data field contains the full resource object at the time of the event.

---

Signature verification

Hydra signs every webhook delivery with HMAC-SHA256 using the subscription’s secret. The signature is sent in the X-Hydra-Signature header.

To verify a delivery:

1. Read the raw request body (do not parse JSON first)
2. Compute HMAC-SHA256(secret, raw_body) and hex-encode the result
3. Compare with the X-Hydra-Signature header value

import crypto from 'crypto';

function verifyWebhook(rawBody, signature, secret) {
	const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

---

Retry behavior

Failed deliveries (non-2xx responses or timeouts) are retried with exponential backoff. The retry cron runs every 5 minutes.

• Deliveries that succeed (2xx) are retained for 30 days, then purged
• Deliveries that fail are retained for 7 days, then purged
• After multiple failed retries, the delivery is marked as permanently failed

---

The webhook object

Field	Type	Description
id	string	Unique ID (prefix: wh_)
url	string	HTTPS delivery endpoint
events	string[]	Subscribed event types
status	string	active or paused
secret	string	HMAC-SHA256 signing secret (prefix: whsec_). Only returned at creation
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp