What are Webhook Subscriptions

Information in our system is constantly changing, long after API calls have been made.

To stay updated on the latest details for users, nodes, subnets and transactions, we recommend subscribing to webhooks. This allows you to register a URL to receive updates as they occur.

Example Use Cases:

  • A previously verified user may be flagged for a sanctions match.

  • A node’s balance may update after a payment has posted.

  • A subnet may be locked after the user is locked for fraud.

  • A transaction may begin processing after it is created.

Webhook Retries

Synapse will send ~5 retries within a 24 hour period for any failed webhook delivery. A webhook delivery is considered a failure unless your server responds with one of the following HTTP codes: 200, 204, 400, 404, 405, 408.

After the failed attempts, we will log the webhooks. That way, even if we fail to deliver the request, you can still access the original request and the reason as to why the webhook failed.

Idempotent Requests

To prevent duplicate creation of users, nodes, subnets and transactions, please use Idempotency Keys for all POST requests. This allows you to safely retry requests without accidentally performing the same operation twice.

For example, if a request to create a transaction fails due to a network connectivity error, you can retry the request with the same idempotency key. If multiple transactions with the same Idempotency Key are submitted, we can prevent a duplicate transaction.

To perform an idempotent request, attach a unique key to any POST request made to the API via the X-SP-IDEMPOTENCY-KEY: header.

Please keep in mind:

  • Idempotency keys expire after 24 hours.

  • It is best practice to wait for a failure response from the POST call before attempting to retry the call.