Docs
/
Madden Leagues
/
Import Automation & Webhooks
Madden Leagues

Import Automation & Webhooks

Configure import completion events, payloads, retries, security, and receiver troubleshooting.

Import automation and webhooks

Import webhooks let a Madden league notify an external service when NeonSportz finishes a selected import stage. Typical receivers include commissioner dashboards, custom Discord bots, reporting pipelines, and other automation that should react only after imported data is ready.

The webhook is an outbound notification. It does not start an import, alter Madden data, or replace NeonSportz’s built-in Discord notifications.

The event body deliberately carries no league data — only which league, stage, season, and week completed. The recommended pattern is to treat the webhook as the trigger and the public API as the source:

  1. Your receiver accepts the event and returns 2xx immediately.
  2. It then calls the read-only API for exactly what it needs — rosters, stats, standings, transactions, or games.
  3. It stores or forwards the result.

Because the event only fires once the stage has finished, the data the API returns is already in place, so nothing has to poll for it or guess when an import completed. The API needs no account or key, and is rate limited per IP address; if a call returns 429, wait for the seconds given in its Retry-After header before retrying.

Where to find it

  1. Open the Madden league.
  2. Select Administration.
  3. Select the Automation tab.
  4. Use the Import Webhook card.

The page is separate from general League Settings. Access requires the league’s Edit League/Admin permission, and webhook settings and delivery details are not exposed through the public league API.

Configure automatic delivery

The Import Webhook card has three settings:

  • Webhook URL: the public HTTP or HTTPS endpoint that receives the event.
  • Automatic trigger: the completed import stage that should send an event.
  • Send automatically: enables or disables automatic delivery.

To configure it:

  1. Enter the receiver’s full URL.
  2. Choose League Info, Rosters, or All Stats.
  3. Enable Send automatically.
  4. Select Save Webhook Settings.
  5. Complete an import that reaches the selected stage.
  6. Return to Automation and review Last delivery.

Only one automatic trigger can be selected at a time. Changing the trigger affects future stage completions; it does not send old import events.

When each trigger fires

Trigger Delivery is queued when
League Info The league metadata import is marked complete.
Rosters League Info is complete and every registered team-roster and free-agent item finishes successfully.
All Stats League Info and Rosters are complete, stat scheduling is finished, and every registered stat item finishes successfully.

These completion rules apply to tracked EA Direct Connect and Madden Companion App imports. A failed or still-pending item prevents the later stage from being reported as complete.

NeonSportz creates at most one automatic delivery for the same import run and stage. Receivers should still deduplicate by delivery ID because a network retry can repeat the HTTP request.

Send the latest completed import manually

Select Send Latest Import to queue a test or one-off delivery for the latest tracked import and its furthest completed stage.

  • A saved Webhook URL is required.
  • Manual delivery works even when Send automatically is disabled.
  • The selected automatic trigger does not limit a manual send. For example, a league configured for All Stats can manually send its latest completed Rosters event when All Stats has not completed yet.
  • If NeonSportz has no completed import stage to send, the request is rejected and no delivery is created.
  • A manual event has manual: true in its JSON payload.

The button queues the request; it does not wait for the external server to finish processing it.

HTTP request format

NeonSportz sends an HTTP POST with Content-Type: application/json and these headers:

  • X-NeonSportz-Event: league_import_completed
  • X-NeonSportz-Delivery: <unique delivery UUID>

The delivery header matches eventId in the body. A representative All Stats event looks like this:

{
  "event": "league_import_completed",
  "eventId": "71ba650d-8f70-46f9-9ea2-5bd434ed26f5",
  "league": "NSL",
  "seasonIndex": 2,
  "stageIndex": 1,
  "weekIndex": 8,
  "importType": "all_stats",
  "completedThrough": "all_stats",
  "status": "completed",
  "completedAt": "2026-08-02T18:42:11Z",
  "manual": false
}

seasonIndex, stageIndex, and weekIndex describe the imported Madden context and can be null when that context was unavailable. importType and completedThrough use league_info, rosters, or all_stats.

Receiver requirements

A reliable receiver should:

  1. Accept an HTTP POST at the exact saved URL.
  2. Parse the JSON body.
  3. Verify that event is league_import_completed.
  4. Deduplicate using X-NeonSportz-Delivery or eventId.
  5. Return any 2xx response quickly, then perform longer work asynchronously.

NeonSportz uses a 3-second connection timeout and a 10-second response timeout. It does not follow redirects, so save the final destination URL rather than a URL that responds with 301, 302, 307, or 308.

Delivery status and retries

The Automation page shows the most recent delivery status:

  • pending: queued or waiting for another retry.
  • sending: currently being attempted.
  • delivered: the receiver returned a 2xx status.
  • failed: delivery stopped because the destination or response was not accepted.

Network failures, 408, 429, and 5xx responses are retried. NeonSportz makes up to eight total attempts, waiting approximately 1, 2, 4, 8, 16, 32, and 60 minutes between retries. Other 4xx responses and redirects fail without this retry schedule.

Webhook delivery runs on the notifications worker queue. Heavy import work can continue independently while the notification worker sends or retries the outbound request.

URL and security rules

Webhook URLs are validated when saved and again immediately before delivery. The URL must:

  • Use HTTP or HTTPS and include a hostname.
  • Resolve only to publicly routable internet addresses.
  • Not resolve to loopback, private-network, link-local, or other non-public addresses.
  • Not contain an embedded username or password.

NeonSportz does not follow redirects and does not send a shared secret, authentication token, or request signature. Use HTTPS and a dedicated, hard-to-guess receiver URL. Do not treat an unsigned webhook as proof of an authorized user action. If the event starts sensitive work, add your own gateway controls and validate the league and expected delivery IDs.

Troubleshooting

Save rejects the URL

  • Confirm the URL starts with http:// or https:// and includes a hostname.
  • Remove credentials such as user:password@ from the URL.
  • Confirm every DNS result is a public internet address.
  • Use the final endpoint instead of a redirecting URL.

Send Latest Import is unavailable or fails

  • Save a non-empty Webhook URL first.
  • Complete at least League Info before sending.
  • Confirm you have Edit League/Admin permission for this league.

Delivery stays pending

  • The receiver may have timed out or returned 408, 429, or 5xx and be waiting for the next retry.
  • Check the receiver’s request logs using X-NeonSportz-Delivery.
  • Avoid repeatedly using manual send while an earlier delivery is retrying.

Delivery fails

  • Read the error shown under Last delivery.
  • Confirm the receiver returns a 2xx response within 10 seconds.
  • Confirm the endpoint does not redirect and remains publicly resolvable.
  • If the receiver returned 4xx, correct its route, validation, or access policy before sending again.

Receiver processes the event twice

Retries can resend the same event after a response is lost. Store the delivery UUID and make repeated requests with that UUID a no-op.