{"openapi":"3.1.0","info":{"title":"Webhook Events","version":"1.0.0","description":"# Justt Webhook Events\n\nThis specification describes the webhook events that Justt sends to notify your application about important events.\nread more at: https://developers.justt.ai/docs/webhook-introduction#\n## Webhook Event Types\n\nJustt sends webhooks for the following events:\n\n- **chargeback.created** - Sent when a new chargeback is created in the system\n- **chargeback.status.updated** - Sent when the PSP status of a chargeback is updated\n- **subscription.cancel_immediately.success** - Sent when a CRM subscription was successfully cancelled after a refund\n- **subscription.cancel_immediately.failed** - Sent when cancelling a CRM subscription failed after a refund\n\n## Webhook Security\n\nAll webhooks are signed using HMAC-SHA256 and include verification headers. You should verify the webhook signature to ensure the request is legitimate.\n\n### Webhook Headers\n\nEach webhook request includes the following headers:\n- `webhook-id`: Unique identifier for the webhook message\n- `webhook-signature`: HMAC-SHA256 signature of the payload (format: v1,signature)\n- `webhook-timestamp`: Unix timestamp when the webhook was sent\n\n## Event Payload Structure\n\nAll webhook events follow a consistent structure:\n- `type`: The event type (e.g., \"chargeback.created\")\n- `timestamp`: ISO 8601 timestamp when the event occurred\n- `data`: The event-specific payload containing the relevant information\n\n## Response Requirements\n\nYour webhook endpoint must:\n- Return a 2xx status code to acknowledge receipt\n- Respond within 30 seconds\n- Handle duplicate events idempotently (same event may be sent multiple times)\n\n## Retry Policy\n\nIf your webhook endpoint doesn't respond with a 2xx status code, Justt will retry the webhook with exponential backoff up to 3 times."},"webhooks":{"chargeback.created":{"post":{"summary":"Chargeback Created webhook","description":"Triggered when a new chargeback is received for the merchant.","operationId":"chargeback.created","tags":["Chargeback Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a chargeback created event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["chargeback.created"],"description":"The event type: chargeback.created"},"data":{"$ref":"#/components/schemas/ChargebackDto"}}}]},"examples":{"example1":{"summary":"Chargeback Created example","value":{"type":"chargeback.created","timestamp":"2022-03-15T09:39:24.514Z","data":{"id":"04318fb0-e4ff-4712-972e-4db99b3fb23c","chargebackId":"QRZ54SXB4K6TF232","referenceAccountId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","integrationId":"stripe_integration_123","psp":"stripe","currency":"USD","amount":100.17,"postingDate":"2022-03-15T09:39:24.514Z","transactionCreatedDate":"2022-03-15T09:39:24.514Z","dueDate":"2022-03-15T09:39:24.514Z","pspStatusChangeDate":"2022-03-15T09:39:24.514Z","pspStatus":"needs_response","status":"waiting_for_data","lifecycleStage":"chargeback","transactionId":"txn_1234567890","reasonCode":"4855","reason":"Goods/Services Not Received","reasonGroup":"fraud","cardScheme":"visa","bin":"424242","cardLastFourDigits":"1234","isEnriched":true,"paymentMethod":"credit_card","billingCountry":"US","arn":"74537604221234567891234","enrichmentRatio":0.85,"externalTransactionIdentifier":"ext_txn_123","merchantReferenceName":"65SD89F08236587G41111","winProbability":80,"roiRecommendation":"Fight","transactionAmount":99.99,"transactionCurrency":"USD"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"chargeback.updated":{"post":{"summary":"Chargeback Updated webhook","description":"Triggered when a chargeback is updated.","operationId":"chargeback.updated","tags":["Chargeback Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a chargeback updated event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["chargeback.updated"],"description":"The event type: chargeback.updated"},"data":{"$ref":"#/components/schemas/ChargebackDto"}}}]},"examples":{"example1":{"summary":"Chargeback Updated example","value":{"type":"chargeback.updated","timestamp":"2022-03-15T09:39:24.514Z","data":{"id":"04318fb0-e4ff-4712-972e-4db99b3fb23c","chargebackId":"QRZ54SXB4K6TF232","referenceAccountId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","integrationId":"stripe_integration_123","psp":"stripe","currency":"USD","amount":100.17,"postingDate":"2022-03-15T09:39:24.514Z","transactionCreatedDate":"2022-03-15T09:39:24.514Z","dueDate":"2022-03-15T09:39:24.514Z","pspStatusChangeDate":"2022-03-15T09:39:24.514Z","pspStatus":"needs_response","status":"waiting_for_data","lifecycleStage":"chargeback","transactionId":"txn_1234567890","reasonCode":"4855","reason":"Goods/Services Not Received","reasonGroup":"fraud","cardScheme":"visa","bin":"424242","cardLastFourDigits":"1234","isEnriched":true,"paymentMethod":"credit_card","billingCountry":"US","arn":"74537604221234567891234","enrichmentRatio":0.85,"externalTransactionIdentifier":"ext_txn_123","merchantReferenceName":"65SD89F08236587G41111","winProbability":80,"roiRecommendation":"Fight","transactionAmount":99.99,"transactionCurrency":"USD"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"chargeback.status.updated":{"post":{"summary":"Chargeback Status Updated webhook","description":"Triggered when a chargeback status update is received.","operationId":"chargeback.status.updated","tags":["Chargeback Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a chargeback status updated event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["chargeback.status.updated"],"description":"The event type: chargeback.status.updated"},"data":{"$ref":"#/components/schemas/ChargebackDto"}}}]},"examples":{"example1":{"summary":"Chargeback Status Updated example","value":{"type":"chargeback.status.updated","timestamp":"2022-03-15T09:39:24.514Z","data":{"id":"04318fb0-e4ff-4712-972e-4db99b3fb23c","chargebackId":"QRZ54SXB4K6TF232","referenceAccountId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","integrationId":"stripe_integration_123","psp":"stripe","currency":"USD","amount":100.17,"postingDate":"2022-03-15T09:39:24.514Z","transactionCreatedDate":"2022-03-15T09:39:24.514Z","dueDate":"2022-03-15T09:39:24.514Z","pspStatusChangeDate":"2022-03-15T09:39:24.514Z","pspStatus":"needs_response","status":"waiting_for_data","lifecycleStage":"chargeback","transactionId":"txn_1234567890","reasonCode":"4855","reason":"Goods/Services Not Received","reasonGroup":"fraud","cardScheme":"visa","bin":"424242","cardLastFourDigits":"1234","isEnriched":true,"paymentMethod":"credit_card","billingCountry":"US","arn":"74537604221234567891234","enrichmentRatio":0.85,"externalTransactionIdentifier":"ext_txn_123","merchantReferenceName":"65SD89F08236587G41111","winProbability":80,"roiRecommendation":"Fight","transactionAmount":99.99,"transactionCurrency":"USD"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"pre_chargeback_alert.received":{"post":{"summary":"Pre Chargeback Alert Received webhook","description":"Triggered when a new pre chargeback alert is received from either CDRN, RDR or Ethoca.","operationId":"pre_chargeback_alert.received","tags":["Alert Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a pre chargeback alert received event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["pre_chargeback_alert.received"],"description":"The event type: pre_chargeback_alert.received"},"data":{"$ref":"#/components/schemas/ExternalAlertResponseDto"}}}]},"examples":{"example1":{"summary":"Pre Chargeback Alert Received example","value":{"type":"pre_chargeback_alert.received","timestamp":"2022-03-15T09:39:24.514Z","data":{"alertTimestamp":"2025-01-02T03:04:05Z","alertType":"issuer_alert","type":"Fraud","arn":"12345678901234567890123","authorizationCode":"301008","internalAlertId":"8a979c83-9a9b-4e2a-9a4a-1a2b3c4d5e6f","provider":"Ethoca","providerAlertId":"ALERT-987654","merchantDescriptor":"Dennis Windows","referenceAccountId":"5f8f5c7a-4c3e-4a2b-9b8a-2f1e0d9c8b7a","transaction":{"transactionId":"txn_00123456789","amount":123.45,"currency":"USD","card":{"bin":"411111","last4":"1234"},"timestamp":"2025-01-02T03:04:05Z"}}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"chargeback.evidence.submitted":{"post":{"summary":"Chargeback Evidence Submitted webhook","description":"Triggered when evidence is successfully submitted to the PSP.","operationId":"chargeback.evidence.submitted","tags":["Chargeback Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a chargeback evidence submitted event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["chargeback.evidence.submitted"],"description":"The event type: chargeback.evidence.submitted"},"data":{"$ref":"#/components/schemas/ISubmitedEvidencePayload"}}}]},"examples":{"example1":{"summary":"Chargeback Evidence Submitted example","value":{"type":"chargeback.evidence.submitted","timestamp":"2022-03-15T09:39:24.514Z","data":{"submitEvidenceId":"sub_1234567890","fileId":"file_1234567890","id":"04318fb0-e4ff-4712-972e-4db99b3fb23c","chargebackId":"QRZ54SXB4K6TF232","referenceAccountId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","status":"inProgress","submittedAt":"2025-01-15T12:34:56.789Z","error":"Network timeout","externalTransactionIdentifier":"ext_txn_123"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"chargeback.accepted":{"post":{"summary":"Chargeback Accepted webhook","description":"Triggered when a chargeback acceptance is successfully confirmed by the PSP","operationId":"chargeback.accepted","tags":["Chargeback Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a chargeback accepted event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["chargeback.accepted"],"description":"The event type: chargeback.accepted"},"data":{"$ref":"#/components/schemas/AcceptedChargebackPayloadDto"}}}]},"examples":{"example1":{"summary":"Chargeback Accepted example","value":{"type":"chargeback.accepted","timestamp":"2022-03-15T09:39:24.514Z","data":{"id":"04318fb0-e4ff-4712-972e-4db99b3fb23c","chargebackId":"QRZ54SXB4K6TF232","referenceAccountId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","status":"inProgress","acceptedAt":"2025-01-15T12:34:56.789Z","error":"Network timeout","externalTransactionIdentifier":"ext_txn_123"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"pre_chargeback_alert.refund.succeeded":{"post":{"summary":"Refund Alert Succeeded webhook","description":"Triggered when the linked transaction to a refunded alert was successfully refunded through the PSP","operationId":"pre_chargeback_alert.refund.succeeded","tags":["Alert Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a refund alert succeeded event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["pre_chargeback_alert.refund.succeeded"],"description":"The event type: pre_chargeback_alert.refund.succeeded"},"data":{"$ref":"#/components/schemas/RefundAlertSucceededDto"}}}]},"examples":{"example1":{"summary":"Refund Alert Succeeded example","value":{"type":"pre_chargeback_alert.refund.succeeded","timestamp":"2022-03-15T09:39:24.514Z","data":{"internalAlertId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","providerId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","providerName":"Ethoca","providerAlertId":"ALERT-987654","referenceAccountId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","psp":{"pspName":"stripe","transactionId":"txn_1234567890","refundId":"re_1234567890","refundedDate":"2025-01-02T03:04:05Z"},"amount":100.17,"currency":"USD","alertTimestamp":"2025-01-02T03:04:05Z"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"pre_chargeback_alert.refund.failed":{"post":{"summary":"Refund Alert Failed webhook","description":"Triggered when a refund alert is failed to be processed","operationId":"pre_chargeback_alert.refund.failed","tags":["Alert Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a refund alert failed event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["pre_chargeback_alert.refund.failed"],"description":"The event type: pre_chargeback_alert.refund.failed"},"data":{"$ref":"#/components/schemas/RefundAlertFailedDto"}}}]},"examples":{"example1":{"summary":"Refund Alert Failed example","value":{"type":"pre_chargeback_alert.refund.failed","timestamp":"2022-03-15T09:39:24.514Z","data":{"internalAlertId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","providerId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","providerName":"Ethoca","providerAlertId":"ALERT-987654","referenceAccountId":"04318fb0-e4ff-4712-972e-4db99b3fb23c","psp":{"pspName":"stripe","transactionId":"txn_1234567890","refundError":"transaction_could_not_matched"},"alertTimestamp":"2025-01-02T03:04:05Z","amount":100.17,"currency":"USD"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"pre_chargeback_alert.transaction_matched":{"post":{"summary":"Alert Transaction Matched webhook","description":"Triggered when an inbound pre-chargeback alert was successfully matched to an underlying transaction. Opt-in only — gated by the additional_event_types account configuration.","operationId":"pre_chargeback_alert.transaction_matched","tags":["Alert Events"],"x-svix-feature-flag":"alert_transaction_matched","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a alert transaction matched event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["pre_chargeback_alert.transaction_matched"],"description":"The event type: pre_chargeback_alert.transaction_matched"},"data":{"$ref":"#/components/schemas/AlertTransactionMatchedDto"}}}]},"examples":{"example1":{"summary":"Alert Transaction Matched example","value":{"type":"pre_chargeback_alert.transaction_matched","timestamp":"2022-03-15T09:39:24.514Z","data":{"alertTimestamp":"2025-01-02T03:04:05Z","alertType":"issuer_alert","type":"Fraud","arn":"12345678901234567890123","authorizationCode":"301008","internalAlertId":"8a979c83-9a9b-4e2a-9a4a-1a2b3c4d5e6f","provider":"Ethoca","providerAlertId":"ALERT-987654","merchantDescriptor":"Dennis Windows","referenceAccountId":"5f8f5c7a-4c3e-4a2b-9b8a-2f1e0d9c8b7a","transaction":{"transactionId":"txn_00123456789","amount":123.45,"currency":"USD","card":{"bin":"411111","last4":"1234"},"timestamp":"2025-01-02T03:04:05Z"},"matchedTransaction":{"transactionId":"txn_00123456789","psp":"stripe"}}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"subscription.cancel_immediately.success":{"post":{"summary":"Cancel Subscription Success webhook","description":"Triggered when a CRM subscription was successfully cancelled after a refund (e.g. Chargebee or Recurly).","operationId":"subscription.cancel_immediately.success","tags":["Alert Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a cancel subscription success event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["subscription.cancel_immediately.success"],"description":"The event type: subscription.cancel_immediately.success"},"data":{"$ref":"#/components/schemas/CancelSubscriptionSuccessDto"}}}]},"examples":{"example1":{"summary":"Cancel Subscription Success example","value":{"type":"subscription.cancel_immediately.success","timestamp":"2022-03-15T09:39:24.514Z","data":{"subscriptionId":"sub_00123456789","transactionId":"txn_00123456789","alertId":"550e8400-e29b-41d4-a716-446655440000","chargebackId":"cbk_00123456789","crmProvider":"chargebee","referenceAccountId":"550e8400-e29b-41d4-a716-446655440000"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}},"subscription.cancel_immediately.failed":{"post":{"summary":"Cancel Subscription Failure webhook","description":"Triggered when cancelling a CRM subscription failed after a refund (e.g. subscription not found or already cancelled).","operationId":"subscription.cancel_immediately.failed","tags":["Alert Events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Unique identifier for the webhook message","schema":{"type":"string","example":"msg_325x4fia2lF0ts0ieuEJzOXAh7X"}},{"name":"webhook-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the webhook payload for verification","schema":{"type":"string","example":"v1,8TEsWJiGYzAHFOGsNP21BMk7owrvEbc0FGqBy0x9Quo="}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix timestamp when the webhook was sent","schema":{"type":"string","example":"1756724044"}}],"requestBody":{"description":"Information about a cancel subscription failure event","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseWebhookPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["subscription.cancel_immediately.failed"],"description":"The event type: subscription.cancel_immediately.failed"},"data":{"$ref":"#/components/schemas/CancelSubscriptionFailureDto"}}}]},"examples":{"example1":{"summary":"Cancel Subscription Failure example","value":{"type":"subscription.cancel_immediately.failed","timestamp":"2022-03-15T09:39:24.514Z","data":{"subscriptionId":"sub_00123456789","transactionId":"txn_00123456789","alertId":"550e8400-e29b-41d4-a716-446655440000","chargebackId":"cbk_00123456789","crmProvider":"chargebee","referenceAccountId":"550e8400-e29b-41d4-a716-446655440000","failureReason":"Subscription not found in provider account","failureCode":"subscription_not_found"}}}}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook signature"},"500":{"description":"Internal server error"}},"security":[{"webhookSignature":[]}]}}},"tags":[{"name":"Chargeback Events","description":"All webhook events related to chargeback operations"},{"name":"Alert Events","description":"All webhook events related to alert operations"}],"components":{"schemas":{"BaseWebhookPayload":{"type":"object","required":["type","timestamp","data"],"properties":{"type":{"type":"string","description":"The type of webhook event"},"timestamp":{"type":"string","format":"date-time","description":"The timestamp when the event occurred","example":"2022-03-15T09:39:24.514Z"},"data":{"description":"The event data payload"}}},"RefundAlertSucceededPspDetailsDto":{"type":"object","required":["pspName","transactionId","refundId","refundedDate"],"properties":{"pspName":{"type":"string","description":"The PSP name","example":"stripe"},"transactionId":{"type":"string","description":"The PSP transaction identifier","example":"txn_1234567890"},"refundId":{"type":"string","description":"The PSP refund identifier","example":"re_1234567890"},"refundedDate":{"type":"string","format":"date-time","description":"The timestamp when the refund was completed","example":"2025-01-02T03:04:05Z"}}},"RefundAlertFailedPspDetailsDto":{"type":"object","required":["pspName"],"properties":{"pspName":{"type":"string","description":"The PSP name","example":"stripe"},"transactionId":{"type":"string","description":"The PSP transaction identifier","example":"txn_1234567890"},"refundError":{"type":"string","enum":["transaction_could_not_matched","psp_issue_permission_missing","psp_issue_technical_issue","transaction_already_refunded"],"description":"Normalized refund error reason","example":"transaction_could_not_matched"}}},"RefundAlertSucceededDto":{"type":"object","required":["internalAlertId","providerId","providerName","providerAlertId","referenceAccountId","psp","amount","currency","alertTimestamp"],"properties":{"internalAlertId":{"type":"string","description":"The internal alert identifier","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"providerId":{"type":"string","description":"The provider ID","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"providerName":{"type":"string","description":"The provider name","example":"Ethoca"},"providerAlertId":{"type":"string","description":"The provider alert identifier","example":"ALERT-987654"},"referenceAccountId":{"type":"string","description":"The merchant account identifier reference","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"psp":{"$ref":"#/components/schemas/RefundAlertSucceededPspDetailsDto"},"amount":{"type":"number","description":"The amount of the alert","example":100.17},"currency":{"type":"string","description":"The currency of the alert","example":"USD"},"alertTimestamp":{"type":"string","format":"date-time","description":"The timestamp when the alert was generated","example":"2025-01-02T03:04:05Z"}}},"RefundAlertFailedDto":{"type":"object","required":["internalAlertId","providerId","providerName","referenceAccountId","providerAlertId","psp","alertTimestamp","amount","currency"],"properties":{"internalAlertId":{"type":"string","description":"The internal alert identifier","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"providerId":{"type":"string","description":"The provider ID","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"providerName":{"type":"string","description":"The provider name","example":"Ethoca"},"providerAlertId":{"type":"string","description":"The provider alert identifier","example":"ALERT-987654"},"referenceAccountId":{"type":"string","description":"The merchant account identifier reference","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"psp":{"$ref":"#/components/schemas/RefundAlertFailedPspDetailsDto"},"alertTimestamp":{"type":"string","format":"date-time","description":"The timestamp when the alert was generated","example":"2025-01-02T03:04:05Z"},"amount":{"type":"number","description":"The amount of the alert","example":100.17},"currency":{"type":"string","description":"The currency of the alert","example":"USD"}}},"MatchedTransactionDto":{"type":"object","required":["transactionId","psp"],"description":"Details of the transaction that was matched to the pre-chargeback alert.","properties":{"transactionId":{"type":"string","description":"The PSP transaction identifier of the matched transaction","example":"txn_00123456789"},"psp":{"type":"string","description":"The PSP that processed the matched transaction","example":"stripe"}}},"AlertTransactionMatchedDto":{"description":"Payload sent when a pre-chargeback alert was successfully matched to an underlying transaction.","allOf":[{"$ref":"#/components/schemas/ExternalAlertResponseDto"},{"type":"object","required":["matchedTransaction"],"properties":{"matchedTransaction":{"$ref":"#/components/schemas/MatchedTransactionDto"}}}]},"CancelSubscriptionSuccessDto":{"type":"object","description":"Payload when a CRM subscription was successfully cancelled after a refund alert","properties":{"subscriptionId":{"type":"string","description":"The CRM subscription identifier","example":"sub_00123456789"},"transactionId":{"type":"string","description":"The original refunded transaction identifier","example":"txn_00123456789"},"alertId":{"type":"string","nullable":true,"description":"The pre-chargeback alert identifier related to the transaction (if any)","example":"550e8400-e29b-41d4-a716-446655440000"},"chargebackId":{"type":"string","nullable":true,"description":"The chargeback identifier that triggered the refund (if any)","example":"cbk_00123456789"},"crmProvider":{"type":"string","enum":["chargebee","recurly"],"description":"The CRM provider (e.g. chargebee or recurly)","example":"chargebee"},"referenceAccountId":{"type":"string","description":"The merchant identifier","example":"550e8400-e29b-41d4-a716-446655440000"}}},"CancelSubscriptionFailureDto":{"type":"object","description":"Payload when cancelling a CRM subscription failed after a refund alert","properties":{"subscriptionId":{"type":"string","description":"The CRM subscription identifier (if resolved)","example":"sub_00123456789"},"transactionId":{"type":"string","description":"The original refunded transaction identifier","example":"txn_00123456789"},"alertId":{"type":"string","nullable":true,"description":"The pre-chargeback alert identifier related to the transaction (if any)","example":"550e8400-e29b-41d4-a716-446655440000"},"chargebackId":{"type":"string","nullable":true,"description":"The chargeback identifier that triggered the refund (if any)","example":"cbk_00123456789"},"crmProvider":{"type":"string","enum":["chargebee","recurly"],"description":"The CRM provider (e.g. chargebee or recurly)","example":"chargebee"},"referenceAccountId":{"type":"string","description":"The merchant identifier","example":"550e8400-e29b-41d4-a716-446655440000"},"failureReason":{"type":"string","description":"Human-readable error description","example":"Subscription not found in provider account"},"failureCode":{"type":"string","description":"Machine-readable error code","example":"subscription_not_found"}}},"AcceptedChargebackPayloadDto":{"type":"object","required":["id","referenceAccountId","chargebackId","status","acceptedAt"],"properties":{"id":{"type":"string","description":"A unique chargeback Identifier set by Justt","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"chargebackId":{"type":"string","description":"A unique chargeback Identifier set by the PSP","example":"QRZ54SXB4K6TF232"},"referenceAccountId":{"type":"string","description":"The merchant account identifier reference","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"status":{"type":"string","description":"The status of the evidence submission","example":"inProgress","enum":["created","inProgress","failed","succeeded"]},"acceptedAt":{"type":"string","format":"date-time","description":"The timestamp when the chargeback was accepted","example":"2025-01-15T12:34:56.789Z"},"error":{"type":"string","description":"Optional error message","example":"Network timeout"},"externalTransactionIdentifier":{"type":"string","description":"External transaction identifier","example":"ext_txn_123"}}},"ISubmitedEvidencePayload":{"type":"object","required":["submitEvidenceId","id","chargebackId","referenceAccountId","status","submittedAt"],"properties":{"submitEvidenceId":{"type":"string","example":"sub_1234567890"},"fileId":{"type":"string","example":"file_1234567890"},"id":{"type":"string","description":"A unique chargeback Identifier set by Justt","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"chargebackId":{"type":"string","description":"A unique chargeback Identifier set by the PSP","example":"QRZ54SXB4K6TF232"},"referenceAccountId":{"type":"string","description":"The merchant account identifier reference","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"status":{"type":"string","description":"The status of the evidence submission","example":"inProgress","enum":["created","inProgress","failed","succeeded"]},"submittedAt":{"type":"string","format":"date-time","description":"The timestamp when the evidence was submitted","example":"2025-01-15T12:34:56.789Z"},"error":{"type":"string","description":"Optional error message","example":"Network timeout"},"externalTransactionIdentifier":{"type":"string","description":"External transaction identifier","example":"ext_txn_123"}}},"ExternalAlertResponseDto":{"type":"object","required":["alertTimestamp","type","internalAlertId","provider","providerAlertId","referenceAccountId","transaction"],"properties":{"alertTimestamp":{"type":"string","format":"date-time","description":"Timestamp when the alert was generated","example":"2025-01-02T03:04:05Z"},"alertType":{"type":"string","description":"Type of the alert","example":"issuer_alert"},"type":{"type":"string","enum":["Fraud","Non-Fraud"],"description":"Type of fraud","example":"Fraud"},"arn":{"type":"string","description":"Acquirer Reference Number","example":"12345678901234567890123"},"authorizationCode":{"type":"string","description":"Authorization code","example":"301008"},"internalAlertId":{"type":"string","format":"uuid","description":"Internal alert identifier","example":"8a979c83-9a9b-4e2a-9a4a-1a2b3c4d5e6f"},"provider":{"type":"string","description":"Alert provider name","example":"Ethoca"},"providerAlertId":{"type":"string","description":"Provider-specific alert identifier","example":"ALERT-987654"},"merchantDescriptor":{"type":"string","description":"Merchant descriptor","example":"Dennis Windows"},"referenceAccountId":{"type":"string","format":"uuid","description":"Reference account identifier","example":"5f8f5c7a-4c3e-4a2b-9b8a-2f1e0d9c8b7a"},"transaction":{"type":"object","required":["transactionId","amount","currency","card","timestamp"],"description":"Transaction details","properties":{"transactionId":{"type":"string","description":"Unique transaction identifier","example":"txn_00123456789"},"amount":{"type":"number","description":"Transaction amount","example":123.45},"currency":{"type":"string","description":"Transaction currency code","example":"USD"},"card":{"type":"object","description":"Card information","properties":{"bin":{"type":"string","description":"First 6 digits of the card number","example":"411111"},"last4":{"type":"string","description":"Last 4 digits of the card number","example":"1234"}}},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp","example":"2025-01-02T03:04:05Z"}}}}},"ChargebackDto":{"type":"object","required":["id","chargebackId","referenceAccountId"],"properties":{"id":{"type":"string","description":"A unique chargeback Identifier set by Justt","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"chargebackId":{"type":"string","description":"A unique chargeback Identifier set by the PSP","example":"QRZ54SXB4K6TF232"},"referenceAccountId":{"type":"string","description":"The merchant account identifier reference","example":"04318fb0-e4ff-4712-972e-4db99b3fb23c"},"integrationId":{"type":"string","description":"The integration ID which is the source of the chargeback","example":"stripe_integration_123"},"psp":{"type":"string","description":"The name of the PSP in which the transaction was processed","example":"stripe","enum":["tabapay","nmi","stripe","paypal","amex","braintree","shopify_payments","amazon_pay","adyen","other","cardpointe","checkout","omnipay","acquiring","chase","nuvei","authorizenet","mollie","firstdata","fiserv","elavon","bluesnap","vantiv","dlocal","payu","payu-latam","worldpay_mai","worldpay_iq","payroc","citi","merlink_drs","credorax","dalenys","worldpay_cb911","worldpay_accertify","discover","elavon_payment_insider","elavon_connect","shift4","payplug","global_payments","square","ebanx","zen","payments_hub","ems_data","maverick","corvia","payroc_canada","tap","sabadell","kushki","worldpay","klarna","paysafe","airwallex","mangopay","ecommpay","iyzico","lighthouse","moka","worldpay_wdp","finix","justt_sandbox","paynearme","get_net","bbva","coinflow"]},"currency":{"type":"string","description":"The currency of the amount","example":"USD"},"amount":{"type":"number","description":"The amount that is being charged back by the issuing bank","example":100.17},"postingDate":{"type":"string","format":"date-time","description":"The date the chargeback was posted","example":"2022-03-15T09:39:24.514Z"},"transactionCreatedDate":{"type":"string","format":"date-time","description":"The date the transaction was processed","example":"2022-03-15T09:39:24.514Z"},"dueDate":{"type":"string","format":"date-time","description":"The date the chargeback is due","example":"2022-03-15T09:39:24.514Z"},"pspStatusChangeDate":{"type":"string","format":"date-time","description":"The date when the chargeback PSP status was last changed","example":"2022-03-15T09:39:24.514Z"},"pspStatus":{"type":"string","description":"The status of the chargeback in the PSP system","example":"needs_response","enum":["needs_response","under_review","won","lost","not_applicable","evidence_not_submitted_by_psp","split","unknown"]},"status":{"type":"string","description":"The status of the chargeback in Justt system","example":"waiting_for_data","enum":["waiting_for_data","building_evidence","pending_psp_results","not_represented"]},"lifecycleStage":{"type":"string","description":"The stage of the chargebacks lifecycle","example":"chargeback","enum":["alert","inquiry","claim","chargeback","second_chargeback","third_chargeback","other"]},"transactionId":{"type":"string","description":"The transaction ID set by the PSP","example":"txn_1234567890"},"reasonCode":{"type":"string","description":"The reason code for the chargeback","example":"4855"},"reason":{"type":"string","description":"The reason for the chargeback","example":"Goods/Services Not Received"},"reasonGroup":{"type":"string","description":"The reason group for the chargeback set by Justt","example":"fraud","enum":["service","fraud","processingError","general","nonCompliance"]},"cardScheme":{"type":"string","description":"The card scheme (Visa, Mastercard, etc.)","example":"visa"},"bin":{"type":"string","description":"The BIN (Bank Identification Number) of the card","example":"424242"},"cardLastFourDigits":{"type":"string","description":"The Last 4 digits of the card","example":"1234"},"isEnriched":{"type":"boolean","description":"Indicates whether the chargeback data has been enriched","example":true},"paymentMethod":{"type":"string","description":"The payment method used for the transaction","example":"credit_card"},"billingCountry":{"type":"string","description":"The country code","example":"US"},"arn":{"type":"string","description":"Acquirer Reference Number","example":"74537604221234567891234"},"enrichmentRatio":{"type":"number","description":"The enrichment ratio of the chargeback metadata","example":0.85},"externalTransactionIdentifier":{"type":"string","description":"External transaction identifier","example":"ext_txn_123"},"merchantReferenceName":{"type":"string","description":"The Merchant identifier in the PSP","example":"65SD89F08236587G41111"},"winProbability":{"type":"number","description":"The win probability percent of Justt for this chargeback, Reach out to the Justt team To learn more","example":80},"roiRecommendation":{"type":"string","description":"The ROI based recommendation of Justt for this chargeback, Reach out to the Justt team To learn more","example":"Fight","enum":["Fight","Accept"]},"transactionAmount":{"type":["number","null"],"description":"The original transaction amount at the time of purchase","example":99.99},"transactionCurrency":{"type":["string","null"],"description":"The currency of the original transaction","example":"USD"}}}},"securitySchemes":{"webhookSignature":{"type":"apiKey","in":"header","name":"svix-signature","description":"HMAC-SHA256 signature of the webhook payload"}}}}