Accept Payments

Webhooks

Webhooks notify your application when a transaction is created or updated. InFlow sends a signed JSON message to your endpoint using HTTP POST.

Notifications include x402 and MPP payments processed through InFlow, even when the buyer pays from their own wallet without an InFlow account.

Set up an endpoint

Open Webhooks in your seller dashboard and add your HTTPS endpoint. Save the generated signing key securely on your server. Configure webhooks separately for sandbox and production.

See the API reference for webhook-management endpoints and their account-access requirements.

Transaction events

The event type is TRANSACTION_CREATED or TRANSACTION_UPDATED. The data object contains the transaction details at the time of the event. Some payments are first recorded at settlement and produce only an update event.

  • eventId identifies the event and stays the same across retries. webhookId identifies your configured webhook.
  • data.transactionId is the InFlow transaction ID. data.transactionHash is the blockchain transaction hash, when available.
  • status is the delivery status. data.status is the payment status; SETTLED indicates successful MPP or x402 settlement.
  • data.amount and data.currency contain the payment amount and currency. Amounts are encoded as strings.

Use data.transactionId to match an event to your purchase or retrieve the latest transaction details with GET /v1/transactions/{transactionId}. The API reference describes the complete payload.

Verify signatures

Verify each message before processing it. The x-signature header has the format t=<timestamp>,v1=<digest>. The timestamp is Unix time in seconds, and the digest is an HMAC-SHA256 signature encoded as 64 lowercase hexadecimal characters.

  • Use the original request body, before JSON parsing or reformatting.
  • Read t and v1 from the signature header. Reject missing or malformed values.
  • Use the signing key as UTF-8 text, not hex-decoded bytes.
  • Compute HMAC-SHA256 over timestamp + "." + rawBody, encoded as UTF-8.
  • Compare the computed digest with v1 using a constant-time comparison. Reject mismatches.
  • To limit replay, we recommend rejecting timestamps more than five minutes before or after your server’s current time.

Each retry receives a fresh signature timestamp. Check t, not the event’s created time.

Java example

This Java 17 method uses the standard library. Pass the original request body bytes, the x-signature header, and your webhook signing key. Return HTTP 400 or 401 without processing the event when verification returns false.

import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static boolean verifyWebhook(byte[] rawBody, String signature, String signingKey)
        throws GeneralSecurityException {
    if (signature == null || !signature.matches("t=[0-9]{1,19},v1=[0-9a-f]{64}")) {
        return false;
    }

    int separator = signature.indexOf(',');
    String timestampText = signature.substring(2, separator);
    long timestamp;
    try {
        timestamp = Long.parseLong(timestampText);
    } catch (NumberFormatException exception) {
        return false;
    }

    long now = Instant.now().getEpochSecond();
    if (timestamp < now - 300 || timestamp > now + 300) {
        return false;
    }

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(signingKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    mac.update((timestampText + ".").getBytes(StandardCharsets.UTF_8));
    byte[] expected = mac.doFinal(rawBody);
    byte[] received = HexFormat.of().parseHex(signature.substring(separator + 4));
    return MessageDigest.isEqual(expected, received);
}

Handle delivery and retries

Return HTTP 2xx to acknowledge an event. InFlow retries other responses and network failures up to 11 times, starting after one minute and doubling the delay with each retry. Redirects are not followed. Disabling or deleting a webhook stops delivery.

Make your webhook handler idempotent: processing the same eventId more than once should have the same effect as processing it once. Events can arrive out of order.

To request redelivery, use POST /v1/events/{eventId}/resend.