Credit note webhooks allow automatic sending of information about created credit notes to your system. This functionality enables easy processing and tracking of credit notes created in Retino directly within your own system.
Activating the Functionality
In the Retino administration, go to Settings > Marketplace
Activate the Credit Note Webhooks add-on
After activation, go to the add-on detail by clicking the Manage button
Enter the URL address of your endpoint where we will send credit note data
Click the Save button
Important: For webhooks to function correctly, you need to implement data reception on your side in the format described below.
Webhook Data Format
Credit note webhooks use the standard Retino webhook system with the retino_credit_note.created event_type.
Example data structure:
{
"created_at": "2023-04-04T09:00:19.249525+00:00",
"event_type": "retino_credit_note.created",
"credit_note": {
"id": "5cae6caf-c1cb-49ed-96bd-2d2837765ffc",
"ticket_id": "5cae6caf-c1cb-49ed-96bd-2d2837765ffc",
"stock": true,
"currency": "CZK",
"language": "cs",
"order_id": "2022000001",
"variable_symbol": "2022000001",
"bank_account": {
"type": "CZECH_BANK_ACCOUNT",
"czech_bank_account": "123456789/0100"
},
"customer": {
"city": "Praha",
"name": "Jakub Novák",
"street": "Hradní",
"country": "CZ",
"postal_code": "11000",
"house_number": "1",
"company_id": "(company ID, can be empty)",
"company_vat_number": "(company VAT, can be empty)"
},
"lines": [
{
"id": "9ff867e8-7f90-4c54-9d65-9212ceceae76",
"name": "Macbook PRO",
"price": 39900,
"vat_rate": 0.21,
"amount": 1,
"variant": "Space black",
"product_id": "MAC_PRO_2023"
}
]
}
}
Data Structure Description
The webhook contains the following main parts:
created_at - date and time of the event creation
event_type - event type (always "retino_credit_note.created")
credit_note - object containing credit note data
Structure of the credit_note object:
id - unique identifier of the credit note
ticket_id - ticket ID in Retino, to which the credit note relates
stock - boolean value indicating whether the credit note affects stock
currency - currency of the credit note (ISO code, e.g., "CZK", "EUR")
language - language of the credit note (ISO code, e.g., "cs", "en")
order_id - order ID to which the credit note relates
variable_symbol - variable symbol for payment identification
bank_account - object with bank account information
customer - object with customer information
lines - array of objects with credit note items
Implementation on Your Side
For successful credit note webhook implementation, you need to:
Create an endpoint on your server that will receive HTTP POST requests
Implement processing of incoming data in JSON format
Verify the request's authenticity using the X-Retino-Secret header (more in webhook documentation)
Respond to the request with a 2xx status code within a 10-second timeframe
Tip: For testing webhook reception, you can use services like webhook.site or RequestBin.
Uploading the Credit Note PDF File (Optional)
After processing the webhooks, you can optionally upload your own credit note PDF document back to Retino using our public API.
Use the endpoint:
PATCH https://app.retino.com/api/v2/retino-credit-notes/{credit_note_id}/
With one of the following request bodies:
Uploading file via URL:
{
"file_url": "https://example.com/path/to/your/file.pdf"
}Uploading file via Base64:
{
"file_base64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoK..."
}
Monitoring and Troubleshooting
You can monitor all sent webhooks and their status in:
Settings > Webhooks - in the detail of a specific webhook
Common issues:
Endpoint is unavailable or does not respond within 10 seconds
Endpoint does not return a 2xx status code
Invalid URL format in settings
In case of repeated failed webhook submissions, we will notify you via email.