> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/api-reference/webhooks.md).

# Webhooks

Webhook subscription management: register, list, get, update, delete the URLs Share calls when domain events fire. Outbound deliveries follow the standardized envelope (see the Webhooks reference) and are retried via the durable outbound queue (`outbound-resilience.md`).

## List webhooks

> Returns the paginated set of webhook subscriptions owned by the authenticated provider.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Webhook subscription management: register, list, get, update, delete the URLs Share calls when domain events fire. Outbound deliveries follow the standardized envelope (see the Webhooks reference) and are retried via the durable outbound queue (`outbound-resilience.md`).","name":"Webhooks"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"WebhookResponseDto":{"properties":{"apiVersion":{"description":"Date-stamped envelope version pinned to this subscription.","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"description":"Human-readable label","type":"object"},"events":{"description":"Subscribed events","items":{"type":"array"},"type":"array"},"headers":{"description":"Headers sent with each webhook POST","items":{"$ref":"#/components/schemas/WebhookHeaderResponseDto"},"type":"array"},"id":{"description":"Webhook subscription ID","format":"uuid","type":"string"},"isActive":{"type":"boolean"},"lastTriggeredAt":{"description":"Last time this webhook was triggered","format":"date-time","type":"object"},"signingSecret":{"description":"Masked signing secret (full value only returned on creation)","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"url":{"description":"URL where Share POSTs event payloads","type":"string"}},"required":["id","url","events","headers","isActive","signingSecret","apiVersion","createdAt","updatedAt"],"type":"object"},"WebhookHeaderResponseDto":{"properties":{"name":{"type":"string"},"value":{"description":"Value with {{signature}} placeholder masked in responses","type":"string"}},"required":["name","value"],"type":"object"}}},"paths":{"/v1/webhooks":{"get":{"description":"Returns the paginated set of webhook subscriptions owned by the authenticated provider.","operationId":"WebhooksController_listWebhooks_v1","parameters":[{"description":"1-based page number. Defaults to 1 when omitted.","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"number"}},{"description":"Number of items per page. Capped at 100 server-side. Defaults to 20 when omitted.","in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookResponseDto"},"type":"array"},"success":{"type":"boolean"}}}]}}},"description":"Paginated list of webhook subscriptions."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"List webhooks","tags":["Webhooks"]}}}}
```

## Register a webhook

> Registers a webhook subscription under the authenticated provider. Each event delivered to the subscription is signed so the receiver can verify authenticity.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Webhook subscription management: register, list, get, update, delete the URLs Share calls when domain events fire. Outbound deliveries follow the standardized envelope (see the Webhooks reference) and are retried via the durable outbound queue (`outbound-resilience.md`).","name":"Webhooks"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"RegisterWebhookRequestDto":{"properties":{"apiVersion":{"description":"Envelope version pinned to this subscription. Date-stamped versioning; defaults to the latest stable version.","enum":["2026-05-22"],"type":"string"},"description":{"description":"Human-readable label for this webhook","type":"string"},"events":{"description":"Events to subscribe to. Legacy `user.*` names are accepted on input and rewritten to the canonical `subscriber.*` form.","items":{"enum":["payment.received","payment.failed","payment.expired","refund.issued","billing.cycle_started","billing.cycle_ending","billing.overdue","billing.suspended","subscriber.created","subscriber.updated","subscriber.suspended","subscriber.activated","subscriber.deleted","subscriber.terminated","subscriber.charge.created","subscription.created","subscription.updated","subscription.plan_change_queued","subscription.plan_change_applied","subscription.plan_change_rejected","subscription.plan_removed_queued","subscription.plan_removed","subscription.deactivated","subscription.override_applied","subscription.override_queued","subscription.override_rejected","installation.created","installation.updated","network.session_started","network.session_ended","network.throttled","plan.created","plan.updated","plan.deleted","user.created","user.updated","user.suspended","user.activated"],"type":"string"},"type":"array"},"headers":{"description":"Custom headers to send with each webhook POST. The X-Share-* delivery headers (signature, timestamp, event-id, event-type, delivery-id, delivery-attempt) are added automatically and cannot be overridden here.","items":{"$ref":"#/components/schemas/WebhookHeaderDto"},"type":"array"},"signingSecret":{"description":"Shared secret used for the X-Share-Signature HMAC-SHA256 over `<timestamp>.<raw-body>`. If omitted, Share generates one.","type":"string"},"url":{"description":"URL the events will be delivered to via HTTP POST. Must be https. Delivery is additionally refused at send time if the host resolves to a loopback, link-local, private, or cloud-metadata address.","type":"string"}},"required":["url","events"],"type":"object"},"WebhookHeaderDto":{"properties":{"name":{"description":"Header name. Custom headers ride alongside the auto-generated X-Share-* delivery headers.","type":"string"},"value":{"description":"Header value. Custom headers may not override X-Share-* delivery headers (X-Share-Signature, X-Share-Timestamp, X-Share-Event-Id, X-Share-Event-Type, X-Share-Delivery-Id, X-Share-Delivery-Attempt).","type":"string"}},"required":["name","value"],"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"WebhookResponseDto":{"properties":{"apiVersion":{"description":"Date-stamped envelope version pinned to this subscription.","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"description":"Human-readable label","type":"object"},"events":{"description":"Subscribed events","items":{"type":"array"},"type":"array"},"headers":{"description":"Headers sent with each webhook POST","items":{"$ref":"#/components/schemas/WebhookHeaderResponseDto"},"type":"array"},"id":{"description":"Webhook subscription ID","format":"uuid","type":"string"},"isActive":{"type":"boolean"},"lastTriggeredAt":{"description":"Last time this webhook was triggered","format":"date-time","type":"object"},"signingSecret":{"description":"Masked signing secret (full value only returned on creation)","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"url":{"description":"URL where Share POSTs event payloads","type":"string"}},"required":["id","url","events","headers","isActive","signingSecret","apiVersion","createdAt","updatedAt"],"type":"object"},"WebhookHeaderResponseDto":{"properties":{"name":{"type":"string"},"value":{"description":"Value with {{signature}} placeholder masked in responses","type":"string"}},"required":["name","value"],"type":"object"}}},"paths":{"/v1/webhooks":{"post":{"description":"Registers a webhook subscription under the authenticated provider. Each event delivered to the subscription is signed so the receiver can verify authenticity.","operationId":"WebhooksController_registerWebhook_v1","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWebhookRequestDto"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/WebhookResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"The newly registered webhook subscription."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Register a webhook","tags":["Webhooks"]}}}}
```

## Get a webhook

> Returns a single webhook subscription owned by the authenticated provider.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Webhook subscription management: register, list, get, update, delete the URLs Share calls when domain events fire. Outbound deliveries follow the standardized envelope (see the Webhooks reference) and are retried via the durable outbound queue (`outbound-resilience.md`).","name":"Webhooks"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"WebhookResponseDto":{"properties":{"apiVersion":{"description":"Date-stamped envelope version pinned to this subscription.","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"description":"Human-readable label","type":"object"},"events":{"description":"Subscribed events","items":{"type":"array"},"type":"array"},"headers":{"description":"Headers sent with each webhook POST","items":{"$ref":"#/components/schemas/WebhookHeaderResponseDto"},"type":"array"},"id":{"description":"Webhook subscription ID","format":"uuid","type":"string"},"isActive":{"type":"boolean"},"lastTriggeredAt":{"description":"Last time this webhook was triggered","format":"date-time","type":"object"},"signingSecret":{"description":"Masked signing secret (full value only returned on creation)","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"url":{"description":"URL where Share POSTs event payloads","type":"string"}},"required":["id","url","events","headers","isActive","signingSecret","apiVersion","createdAt","updatedAt"],"type":"object"},"WebhookHeaderResponseDto":{"properties":{"name":{"type":"string"},"value":{"description":"Value with {{signature}} placeholder masked in responses","type":"string"}},"required":["name","value"],"type":"object"}}},"paths":{"/v1/webhooks/{id}":{"get":{"description":"Returns a single webhook subscription owned by the authenticated provider.","operationId":"WebhooksController_getWebhook_v1","parameters":[{"description":"Webhook subscription identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/WebhookResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"The requested webhook subscription."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Get a webhook","tags":["Webhooks"]}}}}
```

## Update a webhook

> Updates the writable fields of a webhook subscription.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Webhook subscription management: register, list, get, update, delete the URLs Share calls when domain events fire. Outbound deliveries follow the standardized envelope (see the Webhooks reference) and are retried via the durable outbound queue (`outbound-resilience.md`).","name":"Webhooks"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"UpdateWebhookRequestDto":{"properties":{"apiVersion":{"description":"Envelope version pinned to this subscription. Date-stamped versioning.","enum":["2026-05-22"],"type":"string"},"description":{"description":"Human-readable label for this webhook","type":"string"},"events":{"description":"Events to subscribe to (replaces existing list)","items":{"enum":["payment.received","payment.failed","payment.expired","refund.issued","billing.cycle_started","billing.cycle_ending","billing.overdue","billing.suspended","subscriber.created","subscriber.updated","subscriber.suspended","subscriber.activated","subscriber.deleted","subscriber.terminated","subscriber.charge.created","subscription.created","subscription.updated","subscription.plan_change_queued","subscription.plan_change_applied","subscription.plan_change_rejected","subscription.plan_removed_queued","subscription.plan_removed","subscription.deactivated","subscription.override_applied","subscription.override_queued","subscription.override_rejected","installation.created","installation.updated","network.session_started","network.session_ended","network.throttled","plan.created","plan.updated","plan.deleted","user.created","user.updated","user.suspended","user.activated"],"type":"string"},"type":"array"},"headers":{"description":"Headers to send with each webhook POST (replaces existing list)","items":{"$ref":"#/components/schemas/WebhookHeaderDto"},"type":"array"},"isActive":{"description":"Enable or disable this webhook","type":"boolean"},"signingSecret":{"description":"New shared secret for HMAC-SHA256 signature","type":"string"},"url":{"description":"URL where Share will POST event payloads. Must be https. Delivery is additionally refused at send time if the host resolves to a loopback, link-local, private, or cloud-metadata address.","type":"string"}},"type":"object"},"WebhookHeaderDto":{"properties":{"name":{"description":"Header name. Custom headers ride alongside the auto-generated X-Share-* delivery headers.","type":"string"},"value":{"description":"Header value. Custom headers may not override X-Share-* delivery headers (X-Share-Signature, X-Share-Timestamp, X-Share-Event-Id, X-Share-Event-Type, X-Share-Delivery-Id, X-Share-Delivery-Attempt).","type":"string"}},"required":["name","value"],"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"WebhookResponseDto":{"properties":{"apiVersion":{"description":"Date-stamped envelope version pinned to this subscription.","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"description":"Human-readable label","type":"object"},"events":{"description":"Subscribed events","items":{"type":"array"},"type":"array"},"headers":{"description":"Headers sent with each webhook POST","items":{"$ref":"#/components/schemas/WebhookHeaderResponseDto"},"type":"array"},"id":{"description":"Webhook subscription ID","format":"uuid","type":"string"},"isActive":{"type":"boolean"},"lastTriggeredAt":{"description":"Last time this webhook was triggered","format":"date-time","type":"object"},"signingSecret":{"description":"Masked signing secret (full value only returned on creation)","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"url":{"description":"URL where Share POSTs event payloads","type":"string"}},"required":["id","url","events","headers","isActive","signingSecret","apiVersion","createdAt","updatedAt"],"type":"object"},"WebhookHeaderResponseDto":{"properties":{"name":{"type":"string"},"value":{"description":"Value with {{signature}} placeholder masked in responses","type":"string"}},"required":["name","value"],"type":"object"}}},"paths":{"/v1/webhooks/{id}":{"put":{"description":"Updates the writable fields of a webhook subscription.","operationId":"WebhooksController_updateWebhook_v1","parameters":[{"description":"Webhook subscription identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/WebhookResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"The updated webhook subscription."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Update a webhook","tags":["Webhooks"]}}}}
```

## Delete a webhook

> Permanently removes a webhook subscription.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Webhook subscription management: register, list, get, update, delete the URLs Share calls when domain events fire. Outbound deliveries follow the standardized envelope (see the Webhooks reference) and are retried via the durable outbound queue (`outbound-resilience.md`).","name":"Webhooks"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"WebhookResponseDto":{"properties":{"apiVersion":{"description":"Date-stamped envelope version pinned to this subscription.","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"description":"Human-readable label","type":"object"},"events":{"description":"Subscribed events","items":{"type":"array"},"type":"array"},"headers":{"description":"Headers sent with each webhook POST","items":{"$ref":"#/components/schemas/WebhookHeaderResponseDto"},"type":"array"},"id":{"description":"Webhook subscription ID","format":"uuid","type":"string"},"isActive":{"type":"boolean"},"lastTriggeredAt":{"description":"Last time this webhook was triggered","format":"date-time","type":"object"},"signingSecret":{"description":"Masked signing secret (full value only returned on creation)","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"url":{"description":"URL where Share POSTs event payloads","type":"string"}},"required":["id","url","events","headers","isActive","signingSecret","apiVersion","createdAt","updatedAt"],"type":"object"},"WebhookHeaderResponseDto":{"properties":{"name":{"type":"string"},"value":{"description":"Value with {{signature}} placeholder masked in responses","type":"string"}},"required":["name","value"],"type":"object"}}},"paths":{"/v1/webhooks/{id}":{"delete":{"description":"Permanently removes a webhook subscription.","operationId":"WebhooksController_deleteWebhook_v1","parameters":[{"description":"Webhook subscription identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/WebhookResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Webhook subscription deleted."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Delete a webhook","tags":["Webhooks"]}}}}
```