# Webhooks

## List webhook subscriptions

> Get a paginated list of webhook subscriptions with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.1.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-WebhookSubscription":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookSubscription"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed"],"type":"string"}}},"paths":{"/webhooks":{"get":{"description":"Get a paginated list of webhook subscriptions with optional filtering","operationId":"listWebhookSubscriptions","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"string","enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed"]},"description":"Filter by webhook topic","in":"query","name":"topic"},{"schema":{"type":"boolean"},"description":"Filter by active status","in":"query","name":"is_active"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-WebhookSubscription"}}}}},"summary":"List webhook subscriptions","tags":["Webhooks"]}}}}
```

## Subscribe to a webhook

> Subscribe to a webhook with the provided information

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.1.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"SubscribeWebhookInput":{"description":"Subscribe to a webhook","properties":{"endpoint_url":{"type":"string"},"secret_key":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"}},"type":"object"}}},"paths":{"/webhooks":{"post":{"description":"Subscribe to a webhook with the provided information","operationId":"createWebhookSubscription","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Subscribe to a webhook","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeWebhookInput"}}},"description":"Webhook information","required":true}}}}}
```

## Unsubscribe from a webhook

> Remove a webhook subscription by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.1.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/webhooks/{subscription_id}":{"delete":{"description":"Remove a webhook subscription by ID","operationId":"deleteWebhookSubscription","parameters":[{"schema":{"type":"string"},"description":"Subscription ID","in":"path","name":"subscription_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Unsubscribe from a webhook","tags":["Webhooks"]}}}}
```

## List webhook events

> Get a paginated list of webhook events with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.1.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-WebhookEvent":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"WebhookEvent":{"description":"Webhook event information","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"idempotency_key":{"type":"string"},"partner_id":{"type":"string"},"payload":{},"sent_at":{"type":"string"},"sort_key":{"type":"integer"},"status":{"$ref":"#/components/schemas/WebhookEventStatus"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookEventStatus":{"enum":["pending","sent","failed"],"type":"string"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed"],"type":"string"}}},"paths":{"/webhooks/events":{"get":{"description":"Get a paginated list of webhook events with optional filtering","operationId":"listWebhookEvents","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"string","enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed"]},"description":"Filter by webhook topic","in":"query","name":"topic"},{"schema":{"type":"string","enum":["pending","sent","failed"]},"description":"Filter by event status","in":"query","name":"status"},{"schema":{"type":"string"},"description":"Filter events created after this date (ISO 8601)","in":"query","name":"from_date"},{"schema":{"type":"string"},"description":"Filter events created before this date (ISO 8601)","in":"query","name":"to_date"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-WebhookEvent"}}}}},"summary":"List webhook events","tags":["Webhooks"]}}}}
```

## Retry failed webhooks

> Retry all failed webhook events for the partner

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.1.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"RetryWebhooksResponse":{"description":"Response from retrying webhooks","properties":{"message":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/webhooks/retry":{"post":{"description":"Retry all failed webhook events for the partner","operationId":"retryWebhookEvent","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryWebhooksResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Retry failed webhooks","tags":["Webhooks"]}}}}
```