Skip to main content

Setting up Webhooks

Updated

What are webhooks?

Webhooks are automated notifications that Firstbase sends to your systems when events occur in your organization. Instead of repeatedly checking for updates, webhooks deliver real-time notifications directly to an endpoint you control, enabling you to:

  • Send instant Slack notifications when orders are delivered
  • Trigger onboarding workflows in your HRIS when equipment ships
  • Update asset management systems automatically when returns are completed
  • Keep business intelligence dashboards current with real-time order data

Firstbase sends a lightweight notification containing the event type and resource ID. Your system can then fetch the complete details using the Firstbase API.

Before you begin

You'll need:

  • Admin permissions in Firstbase to configure webhooks
  • An endpoint URL that can receive HTTPS POST requests (e.g., https://api.yourcompany.com/webhooks/firstbase)
  • Technical knowledge of how to process HTTP requests and call APIs

Available events:

  • Order events: Created, requires approval, shipped, delivered, delivery exception, cancelled
  • Return events: Submitted, confirmed, cancelled, completed, marked as not returned, kit sent, kit sent back, arrived at processing facility

Important note about third-party integrations:

Webhooks cannot be sent directly to Slack or Jira because they require specific payload formats and authentication. To integrate with these tools, you'll need to:

  1. Set up your own endpoint (or use an integration service like Zapier or Make)
  2. Receive the Firstbase webhook
  3. Fetch full details from the Firstbase API
  4. Transform the data into the format required by Slack/Jira
  5. Forward it with proper authentication

Setting up a webhook

  1. Navigate to API & Integrations in the sidebar, then click Webhooks
  2. Click Add Webhook
  3. Configure your webhook:
    • Name: Give your webhook a descriptive name (e.g., "Order Notifications")
    • Resource Type: Select Order events or Return order events
    • Events: Toggle "All events" ON to receive all events in the category, or toggle OFF to select specific events
    • Target URL: Enter the HTTPS endpoint where notifications will be sent (e.g., https://api.yourcompany.com/webhooks/orders)
    • (Optional) Apply filters to limit which events trigger notifications:
      • Region/Country filter: Select specific countries or the "Europe" region grouping. Leave as "All Regions" to receive events from all locations.
      • Destination type (Order events only): Choose Employee, Office, or All
      • Return destination (Return events only): Choose Firstbase, Office, or All
  4. Click Add Webhook

Your webhook is now configured.

Testing your webhook

Before enabling your webhook for production use, test it to ensure your endpoint can receive notifications:

  1. Locate your webhook in the list
  2. Ensure the webhook is enabled (toggle should be ON)
  3. Click the Test button

Firstbase will send a test payload to your endpoint:

{
  "type": "webhook.test",
  "timestamp": "2026-05-20T15:30:00Z"
}

Your endpoint should respond with a 2xx HTTP status code (200, 201, 202, or 204).

If the test fails, check:

  • URL is correct and publicly accessible
  • Endpoint returns a 2xx status code
  • No firewall blocking Firstbase servers
  • HTTPS certificate is valid

Understanding webhook payloads

When an event occurs, your endpoint receives a JSON payload via HTTP POST:

{
  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "eventType": "UPDATED",
  "resourceType": "ORDER",
  "resourceId": "550e8400-e29b-41d4-a716-446655440000"
}

Fields:

  • eventId: A unique UUID for this event. Use it to de-duplicate deliveries (the same event may be delivered more than once during retries).
  • eventType: The lifecycle action that occurred — one of CREATED, UPDATED, or DELETED.
  • resourceType: The resource type, in uppercase — ORDER or RETURN_ORDER.
  • resourceId: The UUID of the order or return.
  • payload (optional): An object with additional event data. Only present when the source event includes it; many notifications omit it entirely.

Note: The granular event you selected when configuring the webhook (for example, order.shipped vs. order.delivered) determines whether a notification is sent to you. It is not included in the payload — the payload reports only the coarse eventType (CREATED / UPDATED / DELETED). To determine the precise state (for example, shipped vs. delivered), fetch the full resource from the Firstbase API and inspect its status (see "Fetching full details" below).

Why is the payload "thin"?

Firstbase sends minimal data (IDs and the event type only) rather than complete order details because:

  • Smaller payloads mean faster delivery
  • Reduces sensitive data in transit
  • Ensures you always get the most current data when you fetch from the API
  • Simplifies payload maintenance

Fetching full details:

Use the Firstbase API to get complete information, including the current status:

  • Orders: GET /api/v1/orders/{orderId} using the resourceId
  • Returns: GET /api/v1/returns/{returnId} using the resourceId

Authenticate using your API credentials. See the Firstbase API documentation for details.

Monitoring webhook deliveries

View delivery history and troubleshoot issues in the Activity tab:

  1. Navigate to Webhooks → Activity tab
  2. View all delivery attempts with status indicators:
    • Green checkmark: Successful delivery (2xx response)
    • Red X: Failed delivery
  3. Filter by status using the buttons at the top: All, Success, or Failed
  4. Click any delivery entry to expand and view:
    • Full request payload sent
    • Response received from your endpoint
    • HTTP status code
    • Timestamp
  5. For failed deliveries, click Resend to manually retry

Automatic retries:

If delivery fails, Firstbase automatically retries up to 12 times over 2-3 hours using exponential backoff (5 seconds, 10 seconds, 20 seconds, 40 seconds, 1.3 minutes, 2.7 minutes, etc., up to 1 hour between attempts).

Delivery history retention:

Webhook delivery history is retained for 30 days. Consider logging successful receipts on your side if you need longer-term records.

Managing webhooks

Enable or disable:

  • Use the toggle switch on each webhook card to temporarily pause notifications without losing your configuration
  • Disabled webhooks appear with reduced opacity and cannot be tested

Edit:

  • Click the edit button (pencil icon) to modify configuration
  • The edit form appears inline within the webhook card

Delete:

  • Click the delete button (trash icon) to permanently remove a webhook
  • You'll be asked to confirm before deletion

Limits:

  • No limit on number of webhooks
  • No cost for using webhooks
  • Cannot create duplicate webhooks (same URL + same resource type)

Troubleshooting

Webhook deliveries are failing:

  • Check the Activity tab for HTTP status codes and error messages
  • Verify your endpoint URL is correct and publicly accessible
  • Ensure your endpoint responds within 10 seconds (timeout limit)
  • Confirm your endpoint returns a 2xx HTTP status code
  • Check for firewall rules blocking Firstbase servers
  • Verify HTTPS certificate is valid (not expired or self-signed)

Test button is disabled:

  • The webhook must be enabled (toggle ON) to test

Not receiving expected events:

  • Check your event selection (All events vs. specific events)
  • Verify region/country and destination filters aren't excluding events
  • Confirm the webhook is enabled
  • Check if your endpoint is returning non-2xx responses (triggering retries)

Need help?

If you're still experiencing issues, contact Firstbase support with:

  • Webhook configuration details
  • Screenshot from Activity tab showing failed delivery
  • Error messages from your endpoint logs

FAQs

What HTTP response should my endpoint return?

Your endpoint should return a 2xx status code (200, 201, 202, or 204) to indicate successful receipt. Any other response (4xx, 5xx, or timeout) triggers automatic retries.

Can I have multiple webhooks with the same URL?

No, you cannot create multiple webhooks with the same URL and resource type. However, you can:

  • Create one webhook for Orders and another for Returns using the same URL
  • Use "All events" mode and filter events in your code

Can I temporarily disable a webhook?

Yes, use the enable/disable toggle switch. Your configuration is preserved while disabled, and no notifications are sent. Re-enable at any time.

How do region and destination filters work?

Region/Country filter: Receive notifications only for events in selected countries. You can select individual countries or choose "Europe" to include all European countries. Leave as "All Regions" for events from all locations.

Destination type filter (Orders): Filter by Employee (shipments to employees) or Office (shipments to offices).

Return destination filter (Returns): Filter by Firstbase (returns to Firstbase warehouse) or Office (returns to office locations).

How long does the retry mechanism work?

If delivery fails, Firstbase retries up to 12 times over approximately 2-3 hours with increasing delays between attempts. After 12 attempts, the delivery is marked as failed and you can manually resend from the Activity tab.

Is there a limit on webhooks?

No, there's no limit on the number of webhooks you can create, and there's no cost for using webhooks.

How long is delivery history kept?

Delivery history is retained for 30 days from the delivery attempt timestamp.

Related articles

Comments

0 comments

Please sign in to leave a comment.