# Webhook Subscriptions

REST API to create and delete webhook subscriptions (the URLs that receive notifications). Use these endpoints to register or remove your endpoint.

## Create a webhook subscription

> Register a URL to receive webhook notifications. The subscription is\
> scoped to the OAuth application associated with your access token.\
> \
> A unique \`secret\` is generated for each subscription. Use this\
> secret to verify the \`X-Signature\` header on incoming webhook\
> deliveries (HMAC-SHA256).\
> \
> Each URL can only be registered once per OAuth application.<br>

````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Webhook Subscriptions","description":"REST API to create and delete webhook subscriptions (the URLs that\nreceive notifications). Use these endpoints to register or remove your\nendpoint.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"schemas":{"WebhookSubscription":{"type":"object","description":"A webhook subscription that receives event notifications via HTTP POST.\n","required":["id","url","oauth_application_uid","athlete_id","created_at","updated_at"],"properties":{"id":{"type":"integer","format":"int64","description":"Unique identifier"},"url":{"type":"string","format":"uri","description":"The URL that receives webhook POST requests"},"secret":{"type":"string","description":"HMAC-SHA256 signing secret. Use this to verify the `X-Signature`\nheader on incoming webhook deliveries. **This value is only\nreturned when the subscription is first created.** Always present in create response.\n"},"oauth_application_uid":{"type":"string","description":"The UID of the OAuth application this subscription belongs to"},"athlete_id":{"type":"integer","format":"int64","nullable":true,"description":"ID of the athlete who created the subscription"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}},"ValidationError":{"type":"object","description":"A validation error response with a list of error messages","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of validation error messages"}}}}},"paths":{"/api/v1/webhook_subscriptions":{"post":{"tags":["Webhook Subscriptions"],"summary":"Create a webhook subscription","description":"Register a URL to receive webhook notifications. The subscription is\nscoped to the OAuth application associated with your access token.\n\nA unique `secret` is generated for each subscription. Use this\nsecret to verify the `X-Signature` header on incoming webhook\ndeliveries (HMAC-SHA256).\n\nEach URL can only be registered once per OAuth application.\n","operationId":"createWebhookSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The URL that will receive webhook POST requests"}}}}}},"responses":{"201":{"description":"Webhook subscription created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"401":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"404":{"description":"OAuth application not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error (e.g., duplicate URL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}}}}
````

## Delete a webhook subscription

> Remove a webhook subscription. The subscription must belong to the\
> OAuth application associated with your access token.<br>

````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Webhook Subscriptions","description":"REST API to create and delete webhook subscriptions (the URLs that\nreceive notifications). Use these endpoints to register or remove your\nendpoint.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"schemas":{"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/api/v1/webhook_subscriptions/{id}":{"delete":{"tags":["Webhook Subscriptions"],"summary":"Delete a webhook subscription","description":"Remove a webhook subscription. The subscription must belong to the\nOAuth application associated with your access token.\n","operationId":"deleteWebhookSubscription","parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the webhook subscription to delete","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Webhook subscription deleted successfully"},"401":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"403":{"description":"Forbidden - subscription does not belong to your application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````