Skip to main content

Webhooks

Overview​

Those webhooks allow you to receive real-time notifications about status changes and important events related to the Commercial Paper issuance process. When an event occurs, QI Tech automatically sends an HTTP POST payload to the configured URL in your system.

Webhook Configuration​

To receive webhooks, you need to configure an endpoint URL in your system. See the webhook configuration documentation for more details on how to register and manage your webhook URLs.

Authentication and Security​

All webhooks sent by QI Tech include a SIGNATURE header holding a JWT signed with HS256 using the Signature Key shared with the partner. The request body is not signed directly: it enters the token through the payload_md5 claim. This signature must be validated in your system to ensure the authenticity and integrity of the received data. For the validation walkthrough, see the webhook authentication documentation.

Available Events​

Issuer Management​

Issuer Registration Approved​

Sent when an issuer registration is approved by compliance.

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

Issuer Registration Rejected​

Sent when an issuer registration is rejected by compliance.

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

Investor Management​

Investor Registration Approved​

Sent when an investor registration is approved by compliance.

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

Investor Registration Rejected​

Sent when an investor registration is rejected by compliance.

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

Operation Management​

Operation Approved​

Sent when an operation is approved by compliance and is ready to be sent for signature.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "pending_signature_submission"
  }
}

Operation Rejected​

Sent when an operation is rejected in the analysis (automatic pre-analysis or manual compliance review). The operation does not proceed to signature.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "compliance_reproved",
    "reproval_reason": {
      "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue."
    }
  }
}

The reproval_reason field carries the rejection reasons as an object of key and description. In the automatic pre-analysis, each key is the eligibility rule that rejected the operation. The field may come as null when the rejection recorded no reason.

Operation Sent for Signature​

Sent when an operation is sent for signature by the involved parties.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "waiting_signature"
  }
}

Operation Signed and Issued​

Sent when an operation is signed by all parties. This event confirms that the Commercial Paper was successfully issued.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "issued",
    "signed_files_url": "https://storage.googleapis.com/commercial-paper-bucket/89c7f73a-c184-400c-bb2a-dd4424075a4f/signed_files?X-Goog-Algorithm=..."
  }
}

The signed_files_url field carries the download link for a compressed file containing all signed contracts of the operation, available regardless of the signature method used. The link is valid for 7 days from the moment the webhook is sent.

Operation Canceled​

Sent when an operation is canceled.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "canceled"
  }
}

Subscription Management​

Subscription Sent for Signature​

Sent when a subscription is created and sent for investor signature.

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "waiting_signature"
  }
}

Subscription Signed​

Sent when the subscription is signed by all parties and is waiting for payment.

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "waiting_payment"
  }
}

Subscription Completed​

Sent when the subscription is completely finalized after payment confirmation.

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "finished"
  }
}

Subscription Canceled​

Sent when the subscription is canceled because the integralization was rejected in the eligibility analysis. The integralization order and the signature envelope are canceled along with it.

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "canceled",
    "cancellation_reason": "ineligible",
    "ineligible_reasons": {
      "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue."
    }
  }
}

The cancellation_reason field identifies the cancellation motive with a stable value. For ineligible, the ineligible_reasons field carries an object in which each key is the eligibility rule that rejected the integralization and each value is the corresponding description.

Subscription Payment Management​

Payment Receipt Included​

Sent when a payment receipt is included and is waiting for confirmation.

Event Type: subscription_payment.subscription_payment_status_change

Payload:

{
  "event_type": "subscription_payment.subscription_payment_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1",
    "status": "waiting_confirmation"
  }
}

Payment Receipt Approved​

Sent when the payment receipt is approved and confirmed.

Event Type: subscription_payment.subscription_payment_status_change

Payload:

{
  "event_type": "subscription_payment.subscription_payment_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1",
    "status": "confirmed"
  }
}

Event Flow​

Commercial Paper Issuance Flow​

  1. Issuer Registration → issuer_status_change (approved/reproved)
  2. Investor Registration → investor_status_change (approved/reproved)
  3. Operation Creation → operation_status_change (pending_signature_submission)
  4. Sent for Signature → operation_status_change (waiting_signature)
  5. Operation Issued → operation_status_change (issued)

Subscription Flow​

  1. Subscription Creation → subscription_status_change (waiting_signature)
  2. Signature Completed → subscription_status_change (waiting_payment)
  3. Receipt Inclusion → subscription_payment_status_change (waiting_confirmation)
  4. Payment Confirmed → subscription_payment_status_change (confirmed)
  5. Subscription Completed → subscription_status_change (finished)

Best Practices​

  1. Respond quickly: Return an HTTP 2xx status as quickly as possible to confirm webhook receipt.
  2. Asynchronous processing: For time-consuming operations, confirm receipt immediately and process the event asynchronously.
  3. Idempotency: Implement idempotent logic, as webhooks may be resent in case of network failure.
  4. Signature validation: Always validate the JWT in the SIGNATURE header before processing the webhook.
  5. Logs and monitoring: Maintain detailed logs of all received webhooks for auditing and debugging.

References​