> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # Ingest lifecycle event > Report a payment lifecycle event for a prior decision so Specter can keep the case and your fraud backends up to date. Reference the decision via `decision_id`. Specter advances the decision's payment state, forwards the event to the backends that participated in that decision, and stores a log entry with each backend's delivery status. A backend that does not support the event type is reported as `skipped` rather than failing the request. ## OpenAPI ````yaml /products/specter/openapi.yaml post /api/events openapi: 3.1.0 info: contact: email: hello@starfish.team name: Starfish GmbH & Co. KG url: https://hellgate.io/cpa/specter description: Composable decision engine and fraud prevention service. license: name: Hellgate API Terms url: https://hellgate.io/terms-and-conditions title: Specter API version: '1.0' servers: - description: Managed instance of Specter url: https://{instance}.{env}.on-hellgate.cloud variables: instance: default: my-instance description: Your unique instance slug, provided during onboarding. env: default: eu1 description: Deployment environment (currently eu1). security: [] tags: - description: Evaluate transactions and retrieve decision results. name: Decisions - description: Close decisions that were flagged for manual review. name: Resolutions - description: Report payment lifecycle events for a prior decision. name: Lifecycle Events - description: Manage rulesets and their activation lifecycle. name: Rulesets - description: Configure interceptors and intercept live payment requests. name: Interceptors - description: Subscribe to decision and event notifications. name: Webhooks - description: Manage blocked field values. name: Blacklist paths: /api/events: post: tags: - Lifecycle Events summary: Ingest lifecycle event description: > Report a payment lifecycle event for a prior decision so Specter can keep the case and your fraud backends up to date. Reference the decision via `decision_id`. Specter advances the decision's payment state, forwards the event to the backends that participated in that decision, and stores a log entry with each backend's delivery status. A backend that does not support the event type is reported as `skipped` rather than failing the request. operationId: events_create parameters: [] requestBody: content: application/json: examples: authorization: summary: Authorization value: data: avs_result: match cvv_result: match outcome: authorized reference: AUTH_001 decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' type: authorization capture: summary: Capture value: data: amount: 4900 currency: EUR decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' type: capture chargeback: summary: Chargeback value: data: amount: 4900 currency: EUR reason_code: '10.4' stage: first_chargeback decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' type: chargeback failed: summary: Failed value: data: reason: insufficient_funds decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' type: failed fraud_report: summary: Fraud report value: data: reported_at: '2026-03-17' source: tc40 decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' type: fraud_report refund: summary: Refund value: data: amount: 4900 currency: EUR reason: Customer return decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' type: refund void: summary: Void value: data: reason: Customer cancelled order decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' type: void schema: $ref: '#/components/schemas/EventRequest' description: Event request required: true responses: '201': content: application/json: examples: chargeback: summary: Chargeback processed value: id: b7e3d2c1-4a5f-4b6c-8d9e-0f1a2b3c4d5e backend_notifications: - backend: vdm error: null status: delivered data: amount: 4900 currency: EUR reason_code: '10.4' stage: first_chargeback decision_id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b occurred_at: '2026-03-20T10:00:00Z' processed_at: '2026-03-20T10:00:01Z' type: chargeback schema: $ref: '#/components/schemas/EventEntry' description: Event entry '401': content: application/json: schema: $ref: '#/components/schemas/Unauthorized' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/Forbidden' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/NotFound' description: Not found '422': content: application/json: schema: $ref: '#/components/schemas/ValidationErrors' description: Validation errors callbacks: {} security: - bearerAuth: [] components: schemas: EventRequest: description: Lifecycle event ingestion request. properties: data: additionalProperties: true description: Event-type-specific payload. See IP-6 schema for per-type fields. type: object decision_id: description: The Specter decision this event is linked to. format: uuid type: string occurred_at: description: When the payment event occurred (ISO 8601). format: date-time type: string type: description: The type of payment lifecycle event. enum: - authorization - capture - refund - void - chargeback - fraud_report - failed type: string required: - type - decision_id - occurred_at - data title: EventRequest type: object EventEntry: description: Persisted lifecycle event log entry. properties: id: format: uuid type: string backend_notifications: items: properties: accepted: description: >- Whether the backend accepted the event. Present when delivered. type: - boolean - 'null' backend: example: vdm type: string backend_reference: description: >- Backend's reference for the notification. Present when delivered. type: - string - 'null' error: description: Error code. Present when failed. type: - string - 'null' reason: description: Why the notification was skipped. Present when skipped. type: - string - 'null' response: description: >- Raw backend response body. Present when a failed HTTP response was received. type: - object - 'null' status: enum: - delivered - skipped - failed type: string type: object type: array data: additionalProperties: true type: object decision_id: format: uuid type: string occurred_at: format: date-time type: string processed_at: format: date-time type: string type: enum: - authorization - capture - refund - void - chargeback - fraud_report - failed type: string title: EventEntry type: object Unauthorized: description: No valid authentication was provided. example: classifier: UNAUTHORIZED code: 401 message: No valid means of authentication was provided properties: classifier: enum: - UNAUTHORIZED type: string code: enum: - 401 type: integer message: type: string required: - classifier - code - message title: Unauthorized type: object Forbidden: description: The token lacks the scope required for this operation. example: classifier: FORBIDDEN code: 403 message: Not allowed to access this resource or feature properties: classifier: enum: - FORBIDDEN type: string code: enum: - 403 type: integer message: type: string required: - classifier - code - message title: Forbidden type: object NotFound: description: The requested resource does not exist. example: classifier: NOT_FOUND code: 404 message: The requested resource does not exist properties: classifier: enum: - NOT_FOUND type: string code: enum: - 404 type: integer message: type: string required: - classifier - code - message title: NotFound type: object ValidationErrors: description: Response shape for request validation failures example: classifier: VALIDATION_ERROR code: 422 validation_errors: - message: must be a positive integer path: limit properties: classifier: example: VALIDATION_ERROR type: string code: example: 422 type: integer validation_errors: items: properties: message: example: must be a positive integer type: string path: example: limit type: string type: object type: array required: - classifier - code - validation_errors title: ValidationErrors type: object securitySchemes: bearerAuth: bearerFormat: JWT description: >- HS256-signed JWT bearer token, obtained via the OAuth2 client-credentials grant (see Authentication). scheme: bearer type: http ````