Official Java SDK for the Volley API. This SDK provides a convenient way to interact with the Volley webhook infrastructure API.
Volley is a webhook infrastructure platform that provides reliable webhook delivery, rate limiting, retries, monitoring, and more.
- Documentation: https://docs.volleyhooks.com
- Getting Started Guide: https://docs.volleyhooks.com/getting-started
- API Reference: https://docs.volleyhooks.com/api
- Authentication Guide: https://docs.volleyhooks.com/authentication
- Security Guide: https://docs.volleyhooks.com/security
- Console: https://app.volleyhooks.com
- Website: https://volleyhooks.com
Add the following dependency to your pom.xml:
<dependency>
<groupId>com.volleyhooks</groupId>
<artifactId>volley-java</artifactId>
<version>1.0.0</version>
</dependency>Add the following to your build.gradle:
dependencies {
implementation 'com.volleyhooks:volley-java:1.0.0'
}import com.volleyhooks.volley.VolleyClient;
import com.volleyhooks.volley.VolleyException;
import com.volleyhooks.volley.models.Organization;
public class Example {
public static void main(String[] args) {
// Create a client with your API token
VolleyClient client = VolleyClient.create("your-api-token");
// Optionally set organization context
client.setOrganizationId(123L);
// List organizations
try {
List<Organization> orgs = client.organizations.list();
for (Organization org : orgs) {
System.out.println("Organization: " + org.getName() + " (ID: " + org.getId() + ")");
}
} catch (VolleyException e) {
System.err.println("Error: " + e.getMessage());
}
}
}Volley uses API tokens for authentication. These are long-lived tokens designed for programmatic access.
- Log in to the Volley Console
- Navigate to Settings → Account → API Token
- Click View Token (you may need to verify your password)
- Copy the token and store it securely
Important: API tokens are non-expiring and provide full access to your account. Keep them secure and rotate them if compromised. See the Security Guide for best practices.
VolleyClient client = VolleyClient.create("your-api-token");For more details on authentication, API tokens, and security, see the Authentication Guide and Security Guide.
When you have multiple organizations, you need to specify which organization context to use for API requests. The API verifies that resources (like projects) belong to the specified organization.
You can set the organization context in two ways:
// Method 1: Set organization ID for all subsequent requests
client.setOrganizationId(123L);
// Method 2: Create client with organization ID
VolleyClient client = VolleyClient.create("your-api-token")
.organizationId(123L)
.build();
// Clear organization context (uses first accessible organization)
client.clearOrganizationId();Note: If you don't set an organization ID, the API uses your first accessible organization by default. For more details, see the API Reference - Organization Context.
// List all organizations
List<Organization> orgs = client.organizations.list();
// Get current organization
Organization org = client.organizations.get(null); // null = use default
// Create organization
Organization newOrg = client.organizations.create(
new CreateOrganizationRequest("My Organization")
);// List projects
List<Project> projects = client.projects.list();
// Create project
Project project = client.projects.create(
new CreateProjectRequest("My Project")
);
// Update project
Project updated = client.projects.update(projectId,
new UpdateProjectRequest("Updated Name")
);
// Delete project
client.projects.delete(projectId);// List sources in a project
List<Source> sources = client.sources.list(projectId);
// Create source
Source source = client.sources.create(projectId,
new CreateSourceRequest("Stripe Webhooks", 10, "none")
);
// Get source details
Source source = client.sources.get(sourceId);
// Update source
Source updated = client.sources.update(sourceId,
new CreateSourceRequest("Updated Source", 20, "none")
);// List destinations
List<Destination> destinations = client.destinations.list(projectId);
// Create destination
Destination dest = client.destinations.create(projectId,
new CreateDestinationRequest("Production Endpoint",
"https://api.example.com/webhooks", 5)
);// List connections
List<Connection> connections = client.projects.getConnections(projectId);
// Create connection
Connection conn = client.connections.create(projectId,
new CreateConnectionRequest(sourceId, destId, "enabled", 5, 3)
);// List events with filters
Events.ListOptions options = new Events.ListOptions();
options.setStatus("failed");
options.setSourceId(sourceId);
options.setLimit(50);
options.setOffset(0);
ListEventsResponse events = client.events.list(projectId, options);
// Get event details
Event event = client.events.get(requestId);
// Replay failed event
ReplayEventResponse result = client.events.replay(
new ReplayEventRequest("evt_abc123def456")
);// List delivery attempts
DeliveryAttempts.ListOptions options = new DeliveryAttempts.ListOptions();
options.setEventId("evt_abc123");
options.setStatus("failed");
options.setLimit(50);
ListDeliveryAttemptsResponse attempts = client.deliveryAttempts.list(projectId, options);// Send a webhook to a source
Map<String, Object> payload = new HashMap<>();
payload.put("event", "user.created");
Map<String, Object> data = new HashMap<>();
data.put("user_id", "123");
data.put("email", "user@example.com");
payload.put("data", data);
String eventId = client.webhooks.send("source_ingestion_id", payload);The SDK throws VolleyException for API errors:
try {
Organization org = client.organizations.get(orgId);
} catch (VolleyException e) {
if (e.isUnauthorized()) {
System.err.println("Authentication failed");
} else if (e.isNotFound()) {
System.err.println("Organization not found");
} else {
System.err.println("API Error: " + e.getMessage() + " (Status: " + e.getStatusCode() + ")");
}
}200- Success201- Created202- Accepted (webhook queued)400- Bad Request (validation error)401- Unauthorized (invalid or missing API token)403- Forbidden (insufficient permissions)404- Not Found429- Rate Limit Exceeded500- Internal Server Error
For more details on error responses, see the API Reference - Response Codes.
You can configure the client with various options:
// Custom base URL (for testing)
VolleyClient client = VolleyClient.create("token")
.baseUrl("https://api-staging.volleyhooks.com")
.build();
// Custom HTTP client
OkHttpClient httpClient = new OkHttpClient.Builder()
.connectTimeout(60, TimeUnit.SECONDS)
.readTimeout(60, TimeUnit.SECONDS)
.build();
VolleyClient client = VolleyClient.create("token")
.httpClient(httpClient)
.build();- Getting Started - Set up your account and create your first webhook
- How It Works - Understand Volley's architecture
- Webhooks Guide - Learn about webhook best practices and signature verification
- Rate Limiting - Configure rate limits for your webhooks
- Monitoring - Monitor webhook delivery and performance
- Best Practices - Webhook development best practices
- FAQ - Frequently asked questions
- Stripe Webhook Localhost Testing
- Retrying Failed Webhooks
- Webhook Event Replay
- Webhook Fan-out
- Multi-Tenant Webhooks
The SDK includes comprehensive unit tests and integration tests.
Unit tests use a mock HTTP server and don't require API credentials:
mvn testIntegration tests make real API calls to the Volley API. You'll need to set your API token:
export VOLLEY_API_TOKEN="your-api-token"
mvn test -Dtest=*IntegrationTestNote: Integration tests are skipped if VOLLEY_API_TOKEN is not set.
- Documentation: https://docs.volleyhooks.com
- Console: https://app.volleyhooks.com
- Website: https://volleyhooks.com
Contributions are welcome! Please feel free to submit a Pull Request.
When contributing:
- Add tests for new functionality
- Ensure all tests pass (
mvn test) - Update documentation as needed
MIT License - see LICENSE file for details.