> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ping

> Public health check endpoint to verify Webhook API connectivity and availability

## Overview

The Ping endpoint is a simple health check that allows you to:

* Test connectivity to Modulus Labs webhook servers
* Verify API availability and response time
* Confirm your network can reach the webhook API endpoints

<Tip>
  This endpoint does not require authentication, making it perfect for quick connectivity tests and uptime monitoring.
</Tip>

<CardGroup cols={2}>
  <Card title="Test Connectivity" icon="signal">
    Verify your application can reach Modulus Labs webhook servers
  </Card>

  <Card title="Check API Availability" icon="heartbeat">
    Confirm the Webhook API is online and responding
  </Card>
</CardGroup>

## Endpoint

```
GET https://webhooks.sbx.moduluslabs.io/ping
```

<Note>
  This endpoint does **not require authentication**. It's a public health check endpoint that anyone can access to verify Webhook API connectivity.
</Note>

## Request

### Headers

| Header   | Value | Required |
| -------- | ----- | -------- |
| `accept` | `*/*` | No       |

### Parameters

This endpoint does not accept any parameters.

### Request Body

This endpoint does not require a request body.

## Response

### Success Response

**Status Code:** `200 OK`

**Headers:**

```
Content-Type: text/html; charset=utf-8
```

**Body:**

```
Pong!
```

<Check>
  If you receive `Pong!`, the Webhook API is available and your network connectivity is working!
</Check>

<ResponseExample>
  ```text 200 Success theme={null}
  Pong!
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "code": "10000001",
    "error": "An unexpected error occurred. Please try again later.",
    "referenceNumber": "097bf60a-bdab-40bf-b615-3c0eae693b86"
  }
  ```

  ```json 503 Service Unavailable theme={null}
  {
    "code": "SERVICE_UNAVAILABLE",
    "error": "Service temporarily unavailable. Please try again later.",
    "referenceNumber": "097bf60a-bdab-40bf-b615-3c0eae693b86"
  }
  ```
</ResponseExample>

### Error Responses

<AccordionGroup>
  <Accordion title="500 Internal Server Error" icon="server">
    **Status Code:** `500`

    **Cause:** Unexpected server error

    **Solution:**

    * Retry the request
    * If the issue persists, contact Modulus Labs support
    * Report the time of occurrence for troubleshooting
  </Accordion>

  <Accordion title="503 Service Unavailable" icon="triangle-exclamation">
    **Status Code:** `503`

    **Cause:** Webhook API temporarily unavailable (maintenance, overload, etc.)

    **Solution:**

    * Wait and retry the request
    * Check Modulus Labs status page for scheduled maintenance
    * Implement exponential backoff for retries
  </Accordion>
</AccordionGroup>

<RequestExample>
  ```bash cURL theme={null}
  curl https://webhooks.sbx.moduluslabs.io/ping

  # Successful response:
  # Pong!
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  async function ping() {
    try {
      const response = await axios.get('https://webhooks.sbx.moduluslabs.io/ping');

      console.log('Response:', response.data);
      // Output: Pong!

      console.log(' Webhook API is reachable!');
    } catch (error) {
      if (error.response) {
        console.error(' Error:', error.response.status);
        console.error('Details:', error.response.data);
      } else {
        console.error(' Request failed:', error.message);
      }
    }
  }

  ping();
  ```

  ```python Python theme={null}
  import requests

  def ping():
      try:
          response = requests.get('https://webhooks.sbx.moduluslabs.io/ping')

          response.raise_for_status()

          print('Response:', response.text)
          # Output: Pong!

          print(' Webhook API is reachable!')

      except requests.exceptions.HTTPError as e:
          print(f' Error: {e.response.status_code}')
          print('Details:', e.response.text)
      except requests.exceptions.RequestException as e:
          print(f' Request failed: {str(e)}')

  if __name__ == '__main__':
      ping()
  ```

  ```php PHP theme={null}
  <?php

  $ch = curl_init('https://webhooks.sbx.moduluslabs.io/ping');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode === 200) {
      echo "Response: $response\n";
      // Output: Pong!
      echo " Webhook API is reachable!\n";
  } else {
      echo " Error: HTTP $httpCode\n";
      echo "Details: $response\n";
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  public class PingExample {
      public static void main(String[] args) throws Exception {
          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://webhooks.sbx.moduluslabs.io/ping"))
              .GET()
              .build();

          HttpResponse<String> response = client.send(
              request,
              HttpResponse.BodyHandlers.ofString()
          );

          if (response.statusCode() == 200) {
              System.out.println("Response: " + response.body());
              // Output: Pong!
              System.out.println(" Webhook API is reachable!");
          } else {
              System.out.println(" Error: HTTP " + response.statusCode());
              System.out.println("Details: " + response.body());
          }
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      // Send request
      resp, err := http.Get("https://webhooks.sbx.moduluslabs.io/ping")
      if err != nil {
          fmt.Printf(" Request failed: %v\n", err)
          return
      }
      defer resp.Body.Close()

      body, _ := io.ReadAll(resp.Body)

      if resp.StatusCode == 200 {
          fmt.Printf("Response: %s\n", string(body))
          // Output: Pong!
          fmt.Println(" Webhook API is reachable!")
      } else {
          fmt.Printf(" Error: HTTP %d\n", resp.StatusCode)
          fmt.Printf("Details: %s\n", string(body))
      }
  }
  ```

  ```csharp C# / .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          await Ping();
      }

      static async Task Ping()
      {
          // Create HttpClient instance
          using var client = new HttpClient();

          try
          {
              // Send GET request
              var response = await client.GetAsync("https://webhooks.sbx.moduluslabs.io/ping");

              // Read response body
              var responseBody = await response.Content.ReadAsStringAsync();

              if (response.IsSuccessStatusCode)
              {
                  Console.WriteLine($"Response: {responseBody}");
                  // Output: Pong!

                  Console.WriteLine(" Webhook API is reachable!");
              }
              else
              {
                  Console.WriteLine($" Error: HTTP {(int)response.StatusCode}");
                  Console.WriteLine($"Details: {responseBody}");
              }
          }
          catch (HttpRequestException e)
          {
              Console.WriteLine($" Request failed: {e.Message}");
          }
          catch (Exception e)
          {
              Console.WriteLine($" Unexpected error: {e.Message}");
          }
      }
  }
  ```
</RequestExample>

## Use Cases

<CardGroup cols={2}>
  <Card title="Integration Testing" icon="flask">
    Verify webhook API connectivity during development and testing
  </Card>

  <Card title="Health Monitoring" icon="heartbeat">
    Include in your application's health check endpoints
  </Card>

  <Card title="CI/CD Pipeline" icon="gears">
    Test API availability in automated deployment workflows
  </Card>

  <Card title="Credential Validation" icon="key">
    Confirm secret key is valid before registering webhooks
  </Card>
</CardGroup>

## Testing Checklist

Use this checklist to verify your Webhook API setup:

<Steps>
  <Step title="Test Basic Connectivity">
    ```bash theme={null}
    curl https://webhooks.sbx.moduluslabs.io/ping
    ```

    Expected: `Pong!` with `200 OK` status
  </Step>

  <Step title="Test Response Time">
    ```bash theme={null}
    curl -w "\nTime: %{time_total}s\n" \
      https://webhooks.sbx.moduluslabs.io/ping
    ```

    Expected: `Pong!` with response time displayed
  </Step>

  <Step title="Test from Your Application">
    Run the ping function from your application code

    Expected: Successfully receives `Pong!`
  </Step>
</Steps>

## Monitoring & Health Checks

Include the Ping endpoint in your monitoring strategy:

```javascript Monitoring Example theme={null}
const HEALTH_CHECK_INTERVAL = 60000; // 1 minute

async function checkWebhookAPIHealth() {
  try {
    const response = await axios.get(
      'https://webhooks.sbx.moduluslabs.io/ping',
      {
        timeout: 5000 // 5 second timeout
      }
    );

    if (response.data === 'Pong!') {
      console.log(' Webhook API is healthy');
      // Update your monitoring dashboard
      metrics.webhookAPIStatus = 'healthy';
    }
  } catch (error) {
    console.error('  Webhook API health check failed');
    metrics.webhookAPIStatus = 'unhealthy';

    // Alert your team
    await alertOncall('Webhook API unreachable', {
      error: error.message,
      timestamp: new Date()
    });
  }
}

setInterval(checkWebhookAPIHealth, HEALTH_CHECK_INTERVAL);
```

## Best Practices

<AccordionGroup>
  <Accordion title="Call Before Webhook Operations" icon="circle-check">
    Test connectivity before creating or updating webhooks:

    ```javascript theme={null}
    async function registerWebhook(webhookUrl, actions) {
      // Test API connectivity first
      try {
        await ping();
      } catch (error) {
        console.error('Webhook API unavailable, skipping registration');
        return null;
      }

      // Proceed with webhook registration
      return await createWebhook(webhookUrl, actions);
    }
    ```
  </Accordion>

  <Accordion title="Implement Timeouts" icon="clock">
    Always set appropriate timeouts to avoid hanging:

    ```javascript theme={null}
    axios.get('https://webhooks.sbx.moduluslabs.io/ping', {
      timeout: 5000 // 5 seconds
    });
    ```
  </Accordion>

  <Accordion title="Log Health Check Results" icon="file-lines">
    Keep track of health check outcomes for debugging:

    ```javascript theme={null}
    const healthCheckLog = {
      timestamp: new Date(),
      status: response.status,
      responseTime: duration,
      success: response.data === 'Pong!'
    };

    await db.healthChecks.insert(healthCheckLog);
    ```
  </Accordion>

  <Accordion title="Use in Startup Checks" icon="rocket">
    Verify Webhook API connectivity when your application starts:

    ```javascript theme={null}
    async function startupChecks() {
      console.log('Checking Webhook API connectivity...');

      try {
        await ping();
        console.log(' Webhook API connection verified');
      } catch (error) {
        console.error(' Cannot reach Webhook API');
        console.error('Application may not receive webhook notifications');
        // Decide whether to proceed or abort startup
      }
    }

    app.listen(3000, async () => {
      await startupChecks();
      console.log('Server running on port 3000');
    });
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Network Timeout" icon="clock">
    **Symptom:** Request times out without response

    **Possible Causes:**

    * Firewall blocking HTTPS requests
    * DNS resolution problems
    * Network connectivity issues

    **Solutions:**

    * Check firewall rules allow HTTPS (port 443)
    * Test DNS resolution: `nslookup webhooks.sbx.moduluslabs.io`
    * Try from a different network
    * Increase timeout duration
  </Accordion>

  <Accordion title="SSL Certificate Error" icon="certificate">
    **Symptom:** SSL/TLS certificate validation fails

    **Possible Causes:**

    * System time incorrect
    * Missing CA certificates
    * Corporate proxy intercepting SSL

    **Solutions:**

    * Verify system time is correct
    * Update SSL certificates on your system
    * Configure proxy settings if applicable
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Webhook" icon="plus" href="/api-reference/webhooks/create">
    Register a webhook endpoint
  </Card>

  <Card title="Authentication Guide" icon="key" href="/docs/qr/authentication">
    Learn about HTTP Basic Auth
  </Card>

  <Card title="Webhooks Overview" icon="book" href="/docs/webhooks/overview">
    Understand the Webhook API
  </Card>

  <Card title="Setup Guide" icon="gear" href="/docs/webhooks/setup">
    Configure your webhook endpoint
  </Card>
</CardGroup>


## OpenAPI

````yaml api-reference/webhooks/openapi.json GET /ping
openapi: 3.1.0
info:
  title: Modulus Labs Webhooks API
  description: >-
    API for managing webhook endpoints to receive QR Ph transaction
    notifications
  version: 1.0.0
servers:
  - url: https://webhooks.sbx.moduluslabs.io
    description: Sandbox
security: []
paths:
  /ping:
    get:
      tags:
        - Health
      summary: Ping
      description: >-
        Public health check endpoint to verify Webhook API connectivity and
        availability. This endpoint does not require authentication.
      operationId: pingWebhooks
      responses:
        '200':
          description: API is available and responding
          content:
            text/plain:
              schema:
                type: string
                example: Pong!
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Error message
        error:
          type: string
          description: Error type

````