Webhooks

Real-time event notifications

Listen for events on your TurraTech account so your integration can automatically trigger reactions. Get notified instantly when payments complete, subscriptions change, or disputes arise.

What are webhooks?

Webhooks are HTTP callbacks that notify your application when events occur in your TurraTech account. Instead of repeatedly polling the API to check for updates, webhooks push data to your server in real-time as events happen.

When an event occurs—like a successful payment or a subscription cancellation—TurraTech sends an HTTP POST request to your configured endpoint URL containing a JSON payload with full event details.

Why use webhooks?

Webhooks enable event-driven architectures. React instantly to payments, provision access when subscriptions start, send confirmation emails, update your database, trigger fulfillment—all automatically.

Webhook payload structure

Example Webhook Payload
{
  "id": "evt_1NqQXYZ123456789",
  "object": "event",
  "type": "payment.succeeded",
  "created": 1704067200,
  "livemode": true,
  "data": {
    "object": {
      "id": "pay_ABC123DEF456",
      "amount": 2000,
      "currency": "gbp",
      "status": "succeeded"
    }
  }
}

Event types

TurraTech sends webhooks for many different events. Subscribe only to the events you need.

`payment.succeeded`

A payment was successfully processed and funds captured.

`payment.failed`

A payment attempt failed due to decline or error.

`payment.refunded`

A payment was fully or partially refunded.

`customer.created`

A new customer record was created.

`subscription.created`

A new subscription was created for a customer.

`subscription.updated`

Subscription was modified (plan, quantity, etc.).

`subscription.deleted`

A subscription was cancelled.

`subscription.trial_will_end`

Trial period will end in 3 days.

`invoice.paid`

An invoice was successfully paid.

`invoice.payment_failed`

An invoice payment attempt failed.

`dispute.created`

A customer initiated a chargeback.

`payout.paid`

Funds were paid out to your bank account.

Setting up webhooks

Follow these steps to start receiving webhook notifications.

Create an endpoint

Build an HTTP endpoint on your server that accepts POST requests. It should be publicly accessible (HTTPS required in production) and respond with a 2xx status code.

Express.js Example
app.post('/webhooks/turratech', (req, res) => {
  const event = req.body;
  console.log(`Received: ${event.type}`);
  res.status(200).json({ received: true });
});

Register the endpoint

Add your endpoint URL in the Dashboard under Developers → Webhooks, or create it via the API. Select which events you want to receive.

Create via API
const endpoint = await turratech.webhookEndpoints.create({
  url: 'https://example.com/webhooks/turratech',
  enabled_events: ['payment.succeeded', 'payment.failed']
});

Verify signatures

Every webhook includes a signature header. Verify it to ensure the request came from TurraTech and prevent attackers from sending fake events.

Signature Verification
const sig = req.headers['turratech-signature'];
const event = turratech.webhooks.constructEvent(
  req.body, sig, endpointSecret
);
// Process verified event

Process asynchronously

Return a 200 response quickly (within 30 seconds), then process the event data asynchronously using a job queue or background worker.

Best practices

Follow these recommendations to build a robust webhook integration.

Handle duplicates

Store processed event IDs. Webhooks may be delivered more than once—your handler should safely handle duplicates.

Respond quickly

Return a 2xx status within 30 seconds. If processing takes longer, we'll retry. Process complex logic asynchronously.

Verify signatures

Always verify the webhook signature before processing. This prevents attackers from sending fake events.

Use HTTPS

Webhook endpoints must use HTTPS in production. HTTP is only accepted for localhost testing.

Monitor deliveries

Check webhook logs in your Dashboard. Monitor for failed deliveries and investigate issues promptly.

Log unknown events

Have a fallback handler that logs unknown event types. This helps with debugging and future-proofs your integration.

Retry behavior

If your endpoint doesn't respond with a 2xx status code, we'll retry with exponential backoff over approximately 3 days.

Attempt	Delay	Total elapsed
1st retry	5 minutes	5 minutes
2nd retry	30 minutes	35 minutes
3rd retry	2 hours	~2.5 hours
4th retry	5 hours	~7.5 hours
5th retry	10 hours	~17.5 hours
6th retry	10 hours	~27.5 hours
7th retry (final)	10 hours	~37.5 hours

After all retries fail

If all attempts fail, the webhook is marked as failed. You can manually resend from the Dashboard or use the API to retrieve missed events.

Ready to integrate webhooks?

Start receiving real-time notifications about your payments today.

Get started API reference