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

# Webhooks Overview

> Real-time event notifications from Sturdy Technologies

## What are Webhooks?

Webhooks allow you to receive real-time notifications about events in your Sturdy Technologies account. When an event occurs (like a transaction completing or a card being created), we send an HTTP POST request to a URL you specify.

## Setting Up Webhooks

1. **Configure your endpoint**: Set up an HTTPS endpoint on your server to receive webhook events
2. **Register your webhook URL**: Contact support or use the dashboard to register your webhook URL
3. **Verify webhook signatures**: Validate incoming webhooks using the signature header
4. **Respond quickly**: Return a `200 OK` response within 5 seconds

## Webhook Payload Structure

All webhook events follow a consistent structure:

```json theme={null}
{
  "event_id": "evt_1234567890",
  "event_type": "transaction.completed",
  "timestamp": "2023-10-01T12:34:56Z",
  "data": {
    // Event-specific data
  }
}
```

### Common Fields

* `event_id`: Unique identifier for this webhook event (use for deduplication)
* `event_type`: The type of event that triggered the webhook
* `timestamp`: ISO 8601 timestamp of when the event occurred
* `data`: Event-specific payload data

## Webhook Events

<CardGroup cols={2}>
  <Card title="Transaction Events" icon="money-bill-transfer" href="/api-reference/webhooks/events#transaction-events">
    Payment completion and failure notifications
  </Card>

  <Card title="Card Events" icon="credit-card" href="/api-reference/webhooks/events#card-events">
    Virtual card lifecycle and transaction events
  </Card>

  <Card title="Account Events" icon="building-columns" href="/api-reference/webhooks/events#account-events">
    Bank account creation and balance updates
  </Card>

  <Card title="User Events" icon="user" href="/api-reference/webhooks/events#user-events">
    User account creation and deletion
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Handle Idempotency">
    Use the `event_id` to prevent processing the same event multiple times.
    Store processed event IDs and check before processing.
  </Accordion>

  {' '}

  <Accordion title="Respond Quickly">
    Return a `200 OK` response immediately. Process the webhook asynchronously to
    avoid timeouts.
  </Accordion>

  {' '}

  <Accordion title="Verify Signatures">
    Always verify the webhook signature to ensure the request came from Sturdy
    Technologies.
  </Accordion>

  <Accordion title="Handle Retries">
    We'll retry failed webhooks with exponential backoff. Make sure your
    endpoint is idempotent.
  </Accordion>
</AccordionGroup>

## Retry Policy

If your endpoint doesn't respond with a `200 OK` status code, we'll retry the webhook:

* Retry 1: After 1 minute
* Retry 2: After 5 minutes
* Retry 3: After 15 minutes
* Retry 4: After 1 hour
* Retry 5: After 6 hours

After 5 failed attempts, the webhook will be marked as failed and won't be retried automatically.

## Testing Webhooks

Use tools like [webhook.site](https://webhook.site) or [ngrok](https://ngrok.com) to test webhooks during development.

## Need Help?

Contact our support team at [support@sturdytechnologies.com](mailto:support@sturdytechnologies.com) if you need assistance setting up webhooks.