Webhooks

When an event related to a PaymentIntent occurs, Coinify will send an HTTP callback to your system using the HTTP POST verb.

For each Coinify environment (sandbox or production) you want to integrate with, you must provide the following to Coinify API Support in order to start receiving callbacks:

• Webhook URL to callback to
• Shared secret in a UUID v4 format used to authenticate callbacks from Coinify.
  In order to generate a shared secret, you can use the following UUID generator.

🚧

Important:

Please provide the shared secret for the production environment via a secure channel directly with the Coinify API support.

Webhook structure

All webhooks are sent as JSON objects, and share the same general structure as described in the following table:

Property	Type	Description
id	string (UUID v4)	Unique identifier for the event. Retries to the same events will share the same id.
time	string (ISO-8601 timestamp)	Timestamp for when the event has occurred.
event	string	Event that occurred.
context	object	Context for this event. Structure is defined by the event.

Below is an example of a webhook payload sent to your notification URL where all properties are listed.

Example event

{
  "id": "aeb7475b-39c4-41ae-8237-d74a7379c355",
  "time": "2020-04-01T12:47:02.147Z",
  "event": "payment-intent.completed",
  "context": {
    "id": "3589cb4a-0830-497d-a92d-c5178eb2ab9f",
    "customerId": "42",
    "amount": "7145.02",
    "currency": "EUR",
    "creditAmount": "7145.02",
    "creditCurrency": "EUR"
}

Find all the available Webhook events and their details by checking the documentation on PaymentIntent Webhooks.

Webhook signature

All webhooks sent from Coinify are signed with a shared secret that is known only by you and Coinify. This ensures the integrity of the data contained in the webhook and also proves that Coinify is the sender of the webhook.

Specifically, the signature uses HMAC-SHA256, using the shared secret as the key and the full HTTP request body (UTF-8 encoded) as the message. The resulting signature is provided in lowercase hexadecimal format in the X-Coinify-Webhook-Signature HTTP header.

For example, the header for the payload {"examplePayload":true} encrypted with the shared key my-shared-secret, looks like:

X-Coinify-Webhook-Signature: bcdbb89e3031905f3cc1a20d16b5f969a17a7d8fa0c26e4a807c2193402d66f4

❗️

Important

Never consume the payload before validating the signature.
Use the recipe below for step-by-step instructions.

🦉

Validate webhook signature

Open Recipe