--- updatedAt: 2026-07-08T10:19:30.000Z agentTools: projectIndex: https://doc.fintecture.com/llms.txt --- # Manage webhooks # Description Webhooks enable you to be notified of an event such as a payment status change in real-time.\ They are [configured in the Console](https://doc.fintecture.com/docs/console-configure-webhooks) in your application and take 4 parameters: | | | | :-------: | :-------------------------------------------------------------------------------------------- | | `url` | The URL where you will listen to Fintecture webhooks and process the resulting message | | `headers` | Optional custom headers to add to the webhook request (e.g. `Content-Type: application/json`) | | `offset` | The delay, in minutes, between the event and the webhook being sent | | `event` | The list of events to which you want the webhook to be called | A webhook is an `application/x-www-form-urlencoded` or `application/json` POST request whose signature is generated with your application's public key (held by Fintecture); you verify it by decrypting the signature with your application's private key, which only you hold. By default, the webhook is sent with Content-Type `application/x-www-form-urlencoded`, however you can specify `application/json` by creating yourself a custom header of type `Content-Type` ( make sure to add the capital C and capital T)

🚧 Important

Verify the signature using your private key, and only then process the order based on the result of the payment.


The content of the signatureString will be the headers listed in the headers component of the Signature, make sure to consider those and in the same order as indicated in the field. These may be subject to change.

```http POST /webhook HTTP/1.1 Host: mywebsite.com Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="date digest x-request-id",signature="h0V0SUbjRhLEP/MiYo0Mgs1N17EuCEmKyQrDjxysc7iSiFXTjvY6qVEoaiRkzB8ZI0J39gGwOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fSTQ2/BSZWx04CjbPv/XUVusnkKVr3W6p+Vn073hAuJn1nKCvDOyl+QnDtstkzT+UacVzDA9L9nyPbbaPQHJobaZuG8TjhnI+Y0PZxneke6OU6fcdPT0uwkEamDOOExcMryHIX1iH5iiPMvLoVA8acqvvMSDYar0rlEQ2J1M4dcowWT8FxLo6C8uqvJIaBYm7Ze0RNJOwY0UBImCVDIuQLJuBjPwjQT5GjTQlg== Digest: SHA-256=wOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fS Date: Mon, 08 Jun 2020 23:11:23 GMT X-Request-ID: 88c414df-6895-48db-8ef3-1fd1ce4272c6 Content-Type: application/x-www-form-urlencoded session_id=b2bca2bcd3b64a32a7da0766df59a7d2&status=payment_created&customer_id=1ef74051a77673de120820fb370dc382&provider=bnpafr&state=mystate&event=payment_session.status.payment_created ```

🚧 Important

Webhook will retry 20x with an exponential time increment if your server doesn't respond with a HTTP code in the 2XX range.

🚧 Important

Webhooks have a timeout time of 20 seconds. If your server doesn't answer in less than 20 seconds we timeout and retry later.

💡 Note

Payment Sessions of type IncomingTransfer will not necessarily contain a reference which maps to an order thus consider whether you should filter out these payment sessions during your integration by returning a dedicated HTTP response status code such as 202.

# Attributes The following attributes are included in the `application/x-www-form-urlencoded` webhooks. These attributes are only sent if they are populated with a value.
| attribute | event | description | | :----------------------: | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session_id` | all | The unique identifier of the payment session | | `customer_id` | all | The unique customer ID which did the payment | | `provider` | all | The financial provider which was used to process the payment | | `state` | all | The state which was sent on the redirection request | | `event` | all | The event which was just triggered | | `status` | `payment_session.status` | The [status](/docs/api-payment-session-status) of the payment session | | `refund_status` | `payment_session.refund_status` | The status of the refund from the original payment | | `refunded_session_id` | `payment_session.refund_status` | The session ID of the original payment session which is being refunded | | `transfer_state` | `payment_session.status`, `payment_session.transfer_states`, `payment_session.received_amount` | The payment session [transfer state](/docs/api-payment-transfer-states) | | `transfer_reason` | `payment_session.status`, `payment_session.transfer_states`, `payment_session.received_amount` | Details about the payment session `transfer_state` | | `type` | `payment_session.status`, `payment_session.received_amount` |
The payment session type
`PayByBank`,`RequestToPay`,`Refund`,
`RequestForPayout`,`Payout`,`BuyNowPayLater`,
`ManualTransfer`,`IncomingTransfer`
| | `amount` | `payment_session.status`, `payment_session.received_amount` | The payment session amount | | `received_amount` | `payment_session.status`, `payment_session.received_amount` | The total amount received on this payment session | | `transaction_amount` | `payment_session.status`, `payment_session.received_amount` | The amount of the latest transaction related to the payment session | | `virtual_beneficiary_id` | all | The virtual beneficiary ID **only if** the payment was received on a virtual beneficiary |

💡 Note

The order of attributes will not change. More attributes can be appended at the end.