Webhooks

Webhooks allow you to receive real-time notifications when events occur in your LabelGrid account. Use webhooks to automate workflows and integrate with external systems.

Note: Webhooks require API access to be enabled on your account. Contact support if you need this feature enabled.

How Webhooks Work

1. You configure a webhook - Specify a URL and which events to listen for
2. An event occurs - For example, a release is delivered to a store
3. LabelGrid sends a POST request - Your server receives the event data
4. Your system processes it - Automate workflows based on the event

---

Accessing Webhooks

1. Click your profile icon in the top-right corner
2. Select Webhooks from the dropdown menu

---

Creating a Webhook

1. Click Create Webhook
2. Enter a Name to identify this webhook
3. Enter the URL where you want to receive notifications
4. Select which Events should trigger this webhook
5. Click Create

Webhook Secret

When you create a webhook, you’ll receive a secret key. Use this to verify that incoming requests are actually from LabelGrid:

• Store the secret securely
• Verify the signature on incoming requests
• If compromised, regenerate the secret

---

Available Events

Configure your webhook to listen for these events:

Event	Description
Delivery Completed	Triggered when a release is successfully delivered to an outlet
Delivery Failed	Triggered when delivery to an outlet fails
Takedown Completed	Triggered when a takedown request completes
Release Review Status Changed	Triggered when a release review status changes
Release Distributed	Triggered when a release is distributed
Payment Statement Ready	Triggered when a payment statement is ready

You can select multiple events for a single webhook, or create separate webhooks for different event types.

---

Managing Webhooks

Viewing Your Webhooks

The webhook list shows:

Column	Description
Name	The webhook name you assigned
URL	Where notifications are sent
Events	Number of events configured
Status	Active or Inactive
Success / Fail	Count of successful and failed deliveries
Last Triggered	When the webhook was last called

Editing a Webhook

1. Click the Edit action on the webhook row
2. Modify the name, URL, or events
3. Click Save

Activating / Deactivating

Toggle a webhook’s active status without deleting it:

• Active - Webhook will receive notifications
• Inactive - Webhook is paused, no notifications sent

Deleting a Webhook

1. Click the Delete action on the webhook row
2. Confirm the deletion

Warning: Deleted webhooks cannot be recovered.

---

Testing Webhooks

Before relying on a webhook in production, test it:

1. Click the Test action on your webhook
2. LabelGrid sends a test payload to your URL
3. Check that your endpoint received and processed it correctly

---

Viewing Webhook Logs

Monitor webhook activity and troubleshoot issues:

1. Click the View Logs action on a webhook
2. See a history of all webhook deliveries

Log Details

Each log entry shows:

Field	Description
Event Type	Which event triggered this delivery
Response Status	HTTP status code from your server
Duration	How long the request took
Attempt	Retry attempt number
Timestamp	When the delivery occurred

---

Webhook Payload Format

When an event occurs, LabelGrid sends a POST request to your URL with a JSON payload:

{
  "event": "delivery.completed",
  "timestamp": "2026-02-02T12:00:00Z",
  "data": {
    // Event-specific data
  }
}

Verifying Webhook Signatures

Each webhook request includes a signature header. Verify this to ensure the request is from LabelGrid:

1. Get the signature from the request header
2. Compute the expected signature using your webhook secret
3. Compare the signatures

---

Retry Behavior

If your endpoint fails to respond (non-2xx status or timeout):

• LabelGrid retries the delivery
• Retries use exponential backoff
• Failed deliveries are logged with the error

Best Practices for Reliability

• Return a 200 OK response quickly
• Process the data asynchronously if needed
• Monitor your failure count
• Check logs if deliveries are failing

---

Use Cases

Automated Notifications

• Send Slack messages when releases go live
• Email your team when deliveries fail
• Update internal dashboards

Workflow Automation

• Trigger marketing campaigns when releases are distributed
• Update your website when new content is available
• Sync status to external project management tools

Monitoring and Alerting

• Get instant alerts for delivery failures
• Track distribution progress in real-time
• Monitor review status changes

---

Troubleshooting

Webhook Not Receiving Events

1. Check status - Is the webhook Active?
2. Verify URL - Is the endpoint accessible from the internet?
3. Check events - Are the right events selected?
4. Review logs - Any errors recorded?

High Failure Count

1. Check your endpoint - Is it returning 200 OK?
2. Check response time - Is it responding within timeout?
3. Review error messages - What’s failing?
4. Test manually - Send a test webhook

Regenerating the Secret

If your webhook secret is compromised:

1. Click Regenerate Secret in webhook settings
2. Update your application with the new secret
3. Old secret immediately stops working

---

Need Help?

If you have questions about webhooks, contact our support team.