# Plays
## What are Webhooks?
Webhooks are user-defined HTTP callbacks that allow different systems to communicate with each other in real-time. When an event occurs in a source system, it sends an HTTP POST request to a predefined URL in the destination system, allowing for immediate data transfer and action.
***
## Webhooks for Inbound
Orbital webhook triggers are a way to initiate Orbital inbound workflows in real- time. When a webhook is triggered, it can activate a series of actions within Orbital, including:
* Data enrichments
* Customer engagements AI agent interactions
* Custom workflow processes
Orbital webhooks are highly scalable mechanisms designed to handle large volumes of real-time data processing. They enable synchronous operations, allowing you to process customer data and take action immediately as events occur in your other systems.
### Setting up Webhooks for Inbound
To configure a webhook in Orbital, follow these steps:
\
**1. Create a New Inbound Workflow**
* Log in to your Orbital account
* Navigate to the Inbound section
* Click on "Create New Inbound"
* Give your workflow a descriptive name
\
**2. Select Webhook as the Trigger Type**
* In the workflow editor, locate the trigger section
* Click on "Select Trigger"
* Choose "Webhook" from the available trigger types and edit Settings
* Define your webhook schema (see below)
* Configure any additional webhook settings if required
\
**3. Defining Your Webhook Schema**
When setting up a webhook trigger, you must define the schema for the data you'll be sending:
* In the workflow trigger settings, define the expected JSON payload structure
* The schema can be nested, path to the field can be defined
* You can include as many fields as needed in your schema
* Each field should have a defined data type
You can modify your webhook schema at any time by returning to the workflow trigger settings\
\
**4.** **Activate the Webhook and Publish the Workflow**
* Configure the subsequent steps in your workflow (enrichments, engagements, AI agents, etc.)
* Review your complete workflow
* Click "Activate" to enable the webhook
* Publish your workflow by clicking "Publish"
**5.** **Obtain your Webhook URL**
After publishing the workflow, Orbital will generate a unique webhook URL for your workflow. This URL will be used to send data to Orbital and trigger your workflow.
* Locate the webhook URL in the workflow details
* Copy this URL to use in your source systems
The format will be: “app.withorbital.com/\/\ˮ
***
## Technical Implementation Details
### **Webhook URL Structure**
The webhook URL automatically identifies your:
* Orbital workspace
* Specific workflow
This means you don't need to include additional authentication parameters in your requests - the URL itself contains the necessary identification information
### **Security Considerations**
* **Treat the URL as a secret**: The webhook URL contains built-in authentication identifiers and should be treated like an API key. Store it securely and never share it publicly.
* **Access control**: Only share the webhook URL with systems and personnel that need to trigger the workflow
### **Protocol Requirements**
* **HTTPS only**: All webhook requests must be sent over HTTPS. HTTP requests will be rejected.
* **POST method**: Webhooks should be triggered using the HTTP POST method.
* **Content-Type header**: All requests must include the *Content-Type: application/json* header
* **JSON body**: The request body must be valid JSON format.
### **Request Format**
When triggering an Orbital webhook, send your data in the following format:
{% hint style="warning" %}
### **Important Payload Requirements**
* The JSON payload **must** exactly match the schema defined in your workflow trigger settings
* Nested JSON structures are not allowed - all values must be at the top level
* No additional keys or metadata should be included beyond what is defined in your schema
* Requests with payloads that don't match the defined schema will be rejected
{% endhint %}
### Response Handling
Orbital webhooks return standard HTTP status codes:
* **200 OK**: The webhook was successfully received and the workflow was triggered.
* **400 Bad Request**: The request was improperly formatted.
* **401 Unauthorized**: The webhook URL is invalid or has been deactivated.
* **429 Too Many Requests**: You've exceeded the rate limit for your workspace.
* **500 Internal Server Error**: An error occurred while processing the webhook.
### Parallel Processing and Workflow Execution
* **Parallel Processing**: Webhook requests can be triggered in parallel and will be processed asynchronously.
* **No Guaranteed Ordering**: The order of execution is not guaranteed when multiple webhooks are triggered simultaneously.
* **Monitoring Runs**: Once a workflow is triggered, you can monitor its execution in the Orbital dashboard under the "Runs" section.
### Rate Limiting
Webhook requests are subject to rate limits based on your workspace:
* Each workspace has a specific limit on the number of webhook requests allowed per minute
* Exceeding this limit will result in a 429 Too Many Requests response
* Consider implementing backoff and retry logic in your systems for rate limit handling
### Best Practices
* **Payload Structure**
* Keep your payload data structured and consistent
* Include only necessary data to optimize performance
* Use descriptive field names for easier mapping in Orbital workflows
* **Error Handling**
* Implement retry logic in your source systems
* Monitor webhook responses to ensure successful delivery Set up alerts for failed webhook deliveries
* **Testing**\
Before implementing a webhook in Production
* Test your webhook with sample data
* Verify the workflow behaves as expected
* Check that all downstream actions are correctly triggered
### Troubleshooting
Common Issues:
* **Webhook not triggering workflow**: Verify the workflow is published and the webhook is activated
* **Receiving error responses**: Check your payload format and ensure it matches the expected structure
* **Workflow not processing data**: Examine your workflow configuration for mapping errors
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.withorbital.com/basics/plays.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
