# Set up Webhooks and Notifications

Because interactions with physical terminals take time (e.g., waiting for a PIN entry), the Get Smart API Cloud returns the final result of a transaction asynchronously.

To receive this result, you must expose a public HTTP endpoint (Webhook) on your server. The API Cloud will send a `POST` request to this URL containing the final transaction details, authorization codes, and receipt data.

## Configuration

You define where to send the notification **per request**. This means you can route different transactions to different endpoints if necessary.

In every API call (Payment, Refund, Pre-authorization), include the `notificacion` object:

```
{
  "info": {
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/payments",
      "correoNotificacion": "admin@merchant.com"
    },
    ...
  }
}
```

* `urlNotificacion`: The primary channel. Must be a publicly accessible HTTPS URL.  
* `correoNotificacion`: The fallback channel. If your server is down or returns an error (non-200), the system will email the result to this address.

## The Notification Payload

When the terminal finishes processing, your server will receive a JSON payload.

**Method:** `POST`

**Content-Type:** `application/json`

### Example Payload

```
{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timeStamp": "20250428 111500",
    "datosRespuesta": {
      "tipoPago": "PAGO",
      "importe": "25.50",
      "moneda": "978",
      "factura": "ORD-2025-001",
      "resultado": "Autorizada",
      "codigoRespuesta": "998877",
      "estado": "F",
      "tarjetaClienteRecibo": "************1234",
      "marcaTarjeta": "1",
      "Literales": {
         "autenticadoPorPin": "OPERACION CON PIN. FIRMA NO NECESARIA."
      }
    }
  },
  "signature": "INCOMING_SERVER_SIGNATURE"
}
```

### Key Fields to Process

| Field | Description |
| :--- | :--- |
| `resultado` | The human-readable result: `Autorizada` or `Denegada`. |
| `codigoRespuesta` | The authorization code (if approved) or error code (if denied). Save this for reconciliation. |
| `estado` | `F` (Finalized), `A` (Cancelled), `G` (Denied), `T` (Technical Error). |
| `Literales` | Contains mandatory text to be printed on the receipt (e.g., "Verification by PIN"). |
| `datosDCC` | Present only if Dynamic Currency Conversion occurred. Contains exchange rate details. |
| `paisTarjeta` | The 3-digit ISO-3166 numeric code of the card's country (e.g., `840` for USA, `724` for Spain). Useful for analytics or fraud logic. |

## Securing Your Webhook

Because your webhook URL is public, anyone could theoretically send fake requests to it. **You must verify the signature of every incoming notification.**

### Verification Steps

1. **Capture the Raw Body:** Read the incoming JSON body.  
2. **Extract `info`:** Separate the `info` object from the `signature`.  
3. **Calculate Hash:**  
   * Minimize the `info` JSON string (remove whitespace).  
   * Append your **merchant key**.  
   * Calculate SHA256.  
4. **Compare:** Check if your calculated hash matches the `signature` in the payload.

> **Security Warning**: If the signatures do not match, **discard the request immediately**. Do not update your order status or release goods.

## Best Practices

### 1. Idempotency

Network retries might cause you to receive the same notification twice. Ensure your system can handle duplicate requests for the same `factura` (Invoice ID) without charging the customer twice or corrupting your database.

### 2. Acknowledge Quickly

Your server should return a `200 OK` status immediately after receiving and storing the webhook data. If you take too long to respond, the API Cloud might consider the delivery a failure and trigger the email fallback.

### 3. Handle Fallbacks

If you receive an email notification (because your server was down), it will contain the same data in a human-readable format. You may need a manual process to update orders based on these emails if your automated system fails.

## Troubleshooting

| Issue | Possible Cause |
| :---- | :---- |
| **Signature Mismatch** | You might be using the wrong environment key (Test vs. Production), or your JSON parser is reordering fields before you calculate the hash. |
| **No Notification Received** | Check your firewall settings. Ensure your server accepts connections from the internet on the specified port. |
| **Email Received Instead** | Your server returned a 4xx/5xx error or timed out, triggering the fallback mechanism. |

## Next Steps

* [**Query Transaction History**](/en/get-smart/get-smart-api-cloud/integration-guides/query-transaction-history)**:** If you missed a webhook, use the Query endpoint to pull the status manually.  
* [**Receipt Printing Specifications**](/en/get-smart/get-smart-api-cloud/reference/receipt-printing-specifications)**:** Learn how to format the data from `Literales` and `datosDCC` onto paper tickets.